openapi: 3.0.3
info:
  title: Generect API
  description: |-
    Welcome to the Generect API documentation. Here we will help you integrate and use our API.

    API base url: `https://api.generect.com` — every path below is relative to this host. Newer endpoints live under `/api/v1/...`, legacy endpoints under `/api/...`; use each path exactly as documented.
    Protocol: `HTTPS`

    # Authentication

    Get your API token from the Generect app settings and send it in the `Authorization` header with the required `Token` prefix.

    Example: `Authorization: Token xxxxxxxxx`

    # Rate limits

    You can request data depending on your data plan and account balance (default: 10000/month). Pricing depends on the operation and the number of results returned, and may increase with additional data flags. For exact pricing, see each endpoint's Pricing section or your billing settings: https://beta.generect.com/settings/billing

    # Note

    _Every endpoint must include the trailing `/`. Requests without the trailing slash may fail._
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.generect.com
paths:
  /api/auth/token/login/:
    post:
      tags:
        - 1. Auth
      summary: Token login
      description: Login to account and get `auth_token`
      operationId: tokenLogin
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  example: example@example.com
                password:
                  type: string
                  example: '12345678'
            examples:
              Token login:
                value:
                  email: example@example.com
                  password: '12345678'
      responses:
        '200':
          description: '200'
          headers:
            Allow:
              schema:
                type: string
                example: POST, OPTIONS
            Content-Length:
              schema:
                type: string
                example: '134'
            Cross-Origin-Opener-Policy:
              schema:
                type: string
                example: same-origin
            Date:
              schema:
                type: string
                example: Wed, 04 Dec 2024 14:43:33 GMT
            Referrer-Policy:
              schema:
                type: string
                example: same-origin
            Server:
              schema:
                type: string
                example: WSGIServer/0.2 CPython/3.11.10
            Vary:
              schema:
                type: string
                example: Accept, Cookie, Origin
            X-Content-Type-Options:
              schema:
                type: string
                example: nosniff
            X-Frame-Options:
              schema:
                type: string
                example: DENY
          content:
            application/json:
              schema:
                type: object
                properties:
                  auth_token:
                    type: string
                    example: '0000011111222223333344444555556666677777'
                  email:
                    type: string
                    example: example@example.com
                  user_id:
                    type: string
                    example: 00000111-1122-2223-3333-444445555566
              examples:
                '200':
                  value:
                    auth_token: '0000011111222223333344444555556666677777'
                    email: example@example.com
                    user_id: 00000111-1122-2223-3333-444445555566
      security:
        - {}
  /api/auth/users/me/:
    get:
      tags:
        - 1. Auth
      summary: Get User (me)
      description: Retrieve the current user's credit balance and account details
      operationId: getUserMe
      responses:
        '200':
          description: '200'
          headers:
            Allow:
              schema:
                type: string
                example: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
            Content-Length:
              schema:
                type: string
                example: '872'
            Cross-Origin-Opener-Policy:
              schema:
                type: string
                example: same-origin
            Date:
              schema:
                type: string
                example: Mon, 02 Dec 2024 20:45:10 GMT
            Referrer-Policy:
              schema:
                type: string
                example: same-origin
            Server:
              schema:
                type: string
                example: WSGIServer/0.2 CPython/3.11.10
            Vary:
              schema:
                type: string
                example: Accept, Origin
            X-Content-Type-Options:
              schema:
                type: string
                example: nosniff
            X-Frame-Options:
              schema:
                type: string
                example: DENY
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance_companies_by_icp:
                    type: number
                    example: -101
                  balance_company_by_link:
                    type: number
                    example: 0
                  balance_email_finder:
                    type: number
                    example: 0
                  balance_email_verifier:
                    type: number
                    example: 0
                  balance_lead_by_link:
                    type: number
                    example: -3
                  balance_leads_by_icp:
                    type: number
                    example: -1719
                  balance_platform:
                    type: number
                    example: 8531
                  beta_tester:
                    type: boolean
                    example: false
                  blocked_balance_platform:
                    type: number
                    example: 0
                  consultancy_hours:
                    type: number
                    example: 3
                  count_parallel_searches:
                    type: number
                    example: 0
                  count_searches_completed_today:
                    type: number
                    example: 0
                  count_searches_in_progress_today:
                    type: number
                    example: 0
                  email:
                    type: string
                    example: admin@example.com
                  full_name:
                    type: string
                    example: ''
                  icp_flow:
                    type: object
                    properties:
                      A:
                        type: string
                        example: '1'
                      active_compaign_count_lead:
                        type: number
                        example: 1000
                      active_compaign_first_icp:
                        type: string
                        example: 'true'
                      active_compaign_first_lead:
                        type: string
                        example: 'true'
                      active_compaign_first_search:
                        type: string
                        example: 'true'
                  is_staff:
                    type: boolean
                    example: true
                  last_invoice_status:
                    type: boolean
                    example: true
                  last_password_changed:
                    type: string
                    example: '2024-10-30T13:09:31'
                  logo:
                    nullable: true
                    example: null
                  max_credits:
                    type: number
                    example: 10000
                  max_parallel_searches:
                    type: number
                    example: 5
                  max_searches_daily:
                    type: number
                    example: 20
                  prev_subscription_status:
                    nullable: true
                    example: null
                  spent_for_emails:
                    type: number
                    example: 303
                  spent_for_export:
                    type: number
                    example: 0
                  subscription:
                    type: string
                    example: Business
                  trial_available:
                    type: boolean
                    example: true
              examples:
                '200':
                  value:
                    balance_companies_by_icp: -101
                    balance_company_by_link: 0
                    balance_email_finder: 0
                    balance_email_verifier: 0
                    balance_lead_by_link: -3
                    balance_leads_by_icp: -1719
                    balance_platform: 8531
                    beta_tester: false
                    blocked_balance_platform: 0
                    consultancy_hours: 3
                    count_parallel_searches: 0
                    count_searches_completed_today: 0
                    count_searches_in_progress_today: 0
                    email: admin@example.com
                    full_name: ''
                    icp_flow:
                      A: '1'
                      active_compaign_count_lead: 1000
                      active_compaign_first_icp: 'true'
                      active_compaign_first_lead: 'true'
                      active_compaign_first_search: 'true'
                    is_staff: true
                    last_invoice_status: true
                    last_password_changed: '2024-10-30T13:09:31'
                    logo: null
                    max_credits: 10000
                    max_parallel_searches: 5
                    max_searches_daily: 20
                    prev_subscription_status: null
                    spent_for_emails: 303
                    spent_for_export: 0
                    subscription: Business
                    trial_available: true
  /api/auth/transactions/:
    get:
      tags:
        - 2. Transactions
      summary: Get List of Transactions
      description: Retrieve a log of API usage, including endpoints accessed and credits consumed.
      operationId: getListOfTransactions
      parameters:
        - name: limit
          in: query
          schema:
            type: string
            example: '100'
          description: Limit of transactions in result
        - name: offset
          in: query
          schema:
            type: string
            example: '0'
          description: Offset in list of transactions
      responses:
        '200':
          description: '200'
          headers:
            Allow:
              schema:
                type: string
                example: GET, HEAD, OPTIONS
            Content-Length:
              schema:
                type: string
                example: '25393'
            Cross-Origin-Opener-Policy:
              schema:
                type: string
                example: same-origin
            Date:
              schema:
                type: string
                example: Mon, 02 Dec 2024 20:50:51 GMT
            Referrer-Policy:
              schema:
                type: string
                example: same-origin
            Server:
              schema:
                type: string
                example: WSGIServer/0.2 CPython/3.11.10
            Vary:
              schema:
                type: string
                example: Accept, Origin
            X-Content-Type-Options:
              schema:
                type: string
                example: nosniff
            X-Frame-Options:
              schema:
                type: string
                example: DENY
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: number
                    example: 8
                  limit:
                    type: number
                    example: 100
                  max_limit:
                    type: number
                    example: 100
                  next:
                    nullable: true
                    example: null
                  offset:
                    type: number
                    example: 5
                  previous:
                    type: string
                    example: https://api.generect.com/api/auth/transactions/?amount__lte=-5&created_at__range=2025-01-07T00%3A30%3A00%2C2025-12-31&limit=100
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        after_balance:
                          type: number
                          example: -2400
                        amount:
                          type: number
                          example: -10
                        balance_type:
                          type: string
                          example: leads_by_icp
                        created_at:
                          type: string
                          example: '2025-01-07T13:01:15.397996'
                        description:
                          type: string
                          example: leads info by ICP
                        id:
                          type: string
                          example: 51a800b8-5c0c-4f0b-9c3c-459ea2a3fad6
                        status:
                          type: string
                          example: success
                        updated_at:
                          type: string
                          example: '2025-01-07T13:01:58.195959'
                    example:
                      - id: 51a800b8-5c0c-4f0b-9c3c-459ea2a3fad6
                        created_at: '2025-01-07T13:01:15.397996'
                        updated_at: '2025-01-07T13:01:58.195959'
                        status: success
                        balance_type: leads_by_icp
                        amount: -10
                        description: leads info by ICP
                        after_balance: -2400
                      - id: eaea3124-c337-41f2-9258-4a043a7ea877
                        created_at: '2025-01-07T11:27:54.628500'
                        updated_at: '2025-01-07T11:28:40.966949'
                        status: success
                        balance_type: leads_by_icp
                        amount: -10
                        description: leads info by ICP
                        after_balance: -2390
                      - id: 9f57c8e5-43c6-4baf-9777-7754fe481362
                        created_at: '2025-01-07T00:31:06.785495'
                        updated_at: '2025-01-07T00:31:40.788266'
                        status: success
                        balance_type: leads_by_icp
                        amount: -10
                        description: leads info by ICP
                        after_balance: -2380
              examples:
                '200':
                  value:
                    count: 8
                    next: 
                    previous: http://localhost:8000/api/auth/transactions/?amount__lte=-5&created_at__range=2025-01-07T00%3A30%3A00%2C2025-12-31&limit=100
                    limit: 100
                    max_limit: 100
                    offset: 5
                    results:
                      - id: 51a800b8-5c0c-4f0b-9c3c-459ea2a3fad6
                        created_at: '2025-01-07T13:01:15.397996'
                        updated_at: '2025-01-07T13:01:58.195959'
                        status: success
                        balance_type: leads_by_icp
                        amount: -10
                        description: leads info by ICP
                        after_balance: -2400
                      - id: eaea3124-c337-41f2-9258-4a043a7ea877
                        created_at: '2025-01-07T11:27:54.628500'
                        updated_at: '2025-01-07T11:28:40.966949'
                        status: success
                        balance_type: leads_by_icp
                        amount: -10
                        description: leads info by ICP
                        after_balance: -2390
                      - id: 9f57c8e5-43c6-4baf-9777-7754fe481362
                        created_at: '2025-01-07T00:31:06.785495'
                        updated_at: '2025-01-07T00:31:40.788266'
                        status: success
                        balance_type: leads_by_icp
                        amount: -10
                        description: leads info by ICP
                        after_balance: -2380

  /api/auth/transactions/spent_credits/:
    get:
      summary: Fetch spent credits transactions
      description: |
        Retrieve a list of spent credits transactions based on the specified period and date range.
      parameters:
        - name: timezone
          in: query
          description: Timezone for date calculations
          required: true
          schema:
            type: string
        - name: period
          in: query
          description: The aggregation period for transactions
          required: true
          schema:
            type: string
            enum: [day, week, month, quarter, year]
        - name: start_date
          in: query
          description: The start date for the transaction filter (ISO 8601 format)
          required: true
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          description: The end date for the transaction filter (ISO 8601 format)
          required: true
          schema:
            type: string
            format: date
      responses:
        '200':
          description: A list of transactions for the specified period and date range
          content:
            application/json:
              schema:
                type: object
                properties:
                  spent_credits:
                    type: object
                    additionalProperties:
                      type: object
                      additionalProperties:
                        type: number
                    example:
                      "2025-01-01T00:00:00":
                        "/api/linkedin/leads/by_icp/": -4428.0
                        "/api/linkedin/companies/by_icp/": -39.0
                        "/api/linkedin/company/by_link/": -5.0
                        "/api/linkedin/lead/by_link/": -3.0
                        "/api/linkedin/email_finder/": -1.0
                        "platform": -9.0
                      "2024-12-01T00:00:00":
                        "/api/linkedin/leads/by_icp/": -383.0
                        "/api/linkedin/company/by_link/": -17.0
                        "/api/linkedin/companies/by_icp/": -156.0
                        "/api/linkedin/lead/by_link/": -6.0
                        "platform": -12.0
                      "2024-11-01T00:00:00":
                        "/api/linkedin/companies/by_icp/": -101.0
                        "/api/linkedin/leads/by_icp/": -1720.0
                        "platform": -1469.0
                  total_spent_credits:
                    type: number
                    example: -8349.0
      security:
        - apiKey: []

  /api/linkedin/leads/by_link/:
    post:
      tags:
        - 3. Leads
      summary: Get Lead by link
      description: Enrich or update your database with detailed lead information from a provided URL. By default, returns cached data for faster response times. Set up_to_the_second_fresh=true for real-time data retrieval.
      operationId: getLeadByLink
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  example: https://www.linkedin.com/company/boris-johnson
                inexact_company:
                  type: boolean
                  example: false
                comments:
                  type: boolean
                  example: false
                people_also_viewed:
                  type: boolean
                  example: false
                  description: Include people also viewed data (+1 credit). Default is false.
                posts:
                  type: boolean
                  example: false
                  description: Include posts data (+1 credit). Default is false.
                up_to_the_second_fresh:
                  type: boolean
                  example: true
                  description: Use real-time search instead of cached data. Default is false for faster response times.
                get_full_experience:
                  type: boolean
                  example: false
                  description: By default, only current jobs (where job_still_working == true) are returned. Set to true to return full work history including past positions.
            examples:
              Get Lead by link:
                value:
                  comments: false
                  inexact_company: false
                  people_also_viewed: false
                  posts: false
                  up_to_the_second_fresh: true
                  get_full_experience: false
                  url: https://www.linkedin.com/company/boris-johnson
      responses:
        '200':
          description: '200'
          headers:
            Allow:
              schema:
                type: string
                example: POST, OPTIONS
            Content-Length:
              schema:
                type: string
                example: '7540'
            Cross-Origin-Opener-Policy:
              schema:
                type: string
                example: same-origin
            Date:
              schema:
                type: string
                example: Mon, 02 Dec 2024 19:57:51 GMT
            Referrer-Policy:
              schema:
                type: string
                example: same-origin
            Server:
              schema:
                type: string
                example: WSGIServer/0.2 CPython/3.11.10
            Vary:
              schema:
                type: string
                example: Accept, Origin
            X-Content-Type-Options:
              schema:
                type: string
                example: nosniff
            X-Frame-Options:
              schema:
                type: string
                example: DENY
          content:
            application/json:
              schema:
                type: object
                properties:
                  amount:
                    type: number
                    example: -1
                  lead:
                    type: object
                    properties:
                      certifications:
                        type: array
                        items: {}
                        example: []
                      company_city:
                        nullable: true
                        example: null
                      company_country:
                        type: string
                        example: France
                      company_description:
                        type: string
                        example: |-
                          ENGIE is a global reference in low-carbon energy and services. With its 97,000 employees, clients, partners and stakeholders, the Group strives every day to accelerate the transition towards a carbon-neutral economy, through reduced energy consumption and more environmentally friendly solutions. Inspired by its purpose statement, ENGIE reconciles economic performance with a positive impact on people and the planet, building on its key businesses (gas, renewable energy, services) to offer competitive solutions to its clients. 

                          We are a united group, committed to inclusiveness and diversity, where everyone can forge their own career path , improve on their skills, and continually enhance their expertise. We work in a caring, flexible, and secure environment that encourages personal and professional development. #WithENGIE 


                          Turnover in 2023: EUR82.6 billion. The Group is listed on the Paris and Brussels stock exchanges (ENGI) and is represented in the main financial indices (CAC 40, Euronext 100, FTSE Euro 100, MSCI Europe) and non-financial indices (DJSI World, Euronext Vigeo Eiris - Europe 120 / France 20, MSCI EMU ESG screened, MSCI EUROPE ESG Universal Select, Stoxx Europe 600 ESG-X).
                      company_headcount_range:
                        type: string
                        example: 10001+
                      company_id:
                        type: string
                        example: '298246'
                      company_image:
                        type: string
                        example: https://media.licdn.com/dms/image/v2/C4D0BAQHQn5EB4SKDyg/company-logo_400_400/company-logo_400_400/0/1630570629615/engie_logo?e=1741219200&v=beta&t=-Ga4LKJPrvzQnNm3PuUG9lkHYwO4IRP1R79TgqSeftc
                      company_industry:
                        type: string
                        example: Utilities
                      company_location:
                        type: string
                        example: France
                      company_name:
                        type: string
                        example: ENGIE
                      company_state:
                        type: string
                        example: ''
                      company_url:
                        type: string
                        example: https://www.linkedin.com/company/boris-johnson
                      company_website:
                        type: string
                        example: https://www.engie.com/en
                      educations:
                        type: array
                        items:
                          type: object
                          properties:
                            degree:
                              type: string
                              example: Certificat de formation generale (CFG)
                            ended_on:
                              type: object
                              properties:
                                month:
                                  type: number
                                  example: 5
                                year:
                                  type: number
                                  example: 2023
                              nullable: true
                            fields_of_study:
                              type: array
                              items:
                                nullable: true
                                example: null
                            started_on:
                              type: object
                              properties:
                                month:
                                  type: number
                                  example: 3
                                year:
                                  type: number
                                  example: 2023
                            university_id:
                              type: string
                              nullable: true
                              example: '14803'
                            university_name:
                              type: string
                              example: CentraleSupelec
                        example:
                          - degree: Certificat de formation generale (CFG)
                            ended_on:
                              month: 5
                              year: 2023
                            fields_of_study: null
                            started_on:
                              month: 3
                              year: 2023
                            university_id: '14803'
                            university_name: CentraleSupelec
                          - degree: Ingenieur
                            ended_on:
                              year: 2007
                            fields_of_study:
                              - Systeme et Reseau
                            started_on:
                              year: 2002
                            university_id: null
                            university_name: EITI
                          - degree: Certification EasyVista
                            ended_on: null
                            fields_of_study: null
                            started_on:
                              year: 2013
                            university_id: null
                            university_name: EasyVista
                          - degree: Certification HP SM 9
                            ended_on: null
                            fields_of_study: null
                            started_on:
                              year: 2012
                            university_id: null
                            university_name: HP
                          - degree: Certification ITIL V2
                            ended_on: null
                            fields_of_study: null
                            started_on:
                              year: 2012
                            university_id: null
                            university_name: ITIL
                      first_name:
                        type: string
                        example: Birama
                      full_name:
                        type: string
                        example: Birama Traoré
                      headline:
                        type: string
                        example: CIO Procurement - Finance - CSR
                      industry:
                        type: string
                        example: IT Services and IT Consulting
                      input_url:
                        type: string
                        example: https://www.linkedin.com/company/boris-johnson
                      is_full_data:
                        type: boolean
                        example: true
                      is_job_seeker:
                        type: boolean
                        example: false
                      is_openlink:
                        type: boolean
                        example: false
                      is_premium:
                        type: boolean
                        example: false
                      is_retired:
                        type: boolean
                        example: false
                      job_description:
                        nullable: true
                        example: null
                      job_ended_on:
                        nullable: true
                        example: null
                      job_location:
                        type: string
                        example: Paris et peripherie
                      job_location_city:
                        nullable: true
                        example: null
                      job_location_country:
                        type: string
                        example: Ethiopia
                      job_location_county:
                        nullable: true
                        example: null
                      job_location_state:
                        nullable: true
                        example: null
                      job_started_on:
                        type: string
                        example: Sep 2023
                      job_still_working:
                        type: boolean
                        example: true
                      job_title:
                        type: string
                        example: CIO Procurement - Finance - CSR
                      jobs:
                        type: array
                        items:
                          type: object
                          properties:
                            company_city:
                              nullable: true
                              example: null
                            company_country:
                              type: string
                              example: France
                            company_description:
                              type: string
                              example: |-
                                ENGIE is a global reference in low-carbon energy and services. With its 97,000 employees, clients, partners and stakeholders, the Group strives every day to accelerate the transition towards a carbon-neutral economy, through reduced energy consumption and more environmentally friendly solutions. Inspired by its purpose statement, ENGIE reconciles economic performance with a positive impact on people and the planet, building on its key businesses (gas, renewable energy, services) to offer competitive solutions to its clients. 

                                We are a united group, committed to inclusiveness and diversity, where everyone can forge their own career path , improve on their skills, and continually enhance their expertise. We work in a caring, flexible, and secure environment that encourages personal and professional development. #WithENGIE 


                                Turnover in 2023: EUR82.6 billion. The Group is listed on the Paris and Brussels stock exchanges (ENGI) and is represented in the main financial indices (CAC 40, Euronext 100, FTSE Euro 100, MSCI Europe) and non-financial indices (DJSI World, Euronext Vigeo Eiris - Europe 120 / France 20, MSCI EMU ESG screened, MSCI EUROPE ESG Universal Select, Stoxx Europe 600 ESG-X).
                            company_headcount_range:
                              type: string
                              example: 10001+
                            company_id:
                              type: string
                              example: '298246'
                            company_image:
                              type: string
                              example: https://media.licdn.com/dms/image/v2/C4D0BAQHQn5EB4SKDyg/company-logo_400_400/company-logo_400_400/0/1630570629615/engie_logo?e=1741219200&v=beta&t=-Ga4LKJPrvzQnNm3PuUG9lkHYwO4IRP1R79TgqSeftc
                            company_industry:
                              type: string
                              example: Utilities
                            company_location:
                              type: string
                              example: France
                            company_name:
                              type: string
                              example: ENGIE
                            company_state:
                              type: string
                              example: ''
                            company_url:
                              type: string
                              example: https://www.linkedin.com/company/engie/
                            company_website:
                              type: string
                              example: https://www.engie.com/en
                            job_description:
                              nullable: true
                              example: null
                            job_ended_on:
                              nullable: true
                              example: null
                            job_location:
                              type: string
                              example: Paris et peripherie
                            job_location_city:
                              nullable: true
                              example: null
                            job_location_country:
                              type: string
                              example: Ethiopia
                            job_location_county:
                              nullable: true
                              example: null
                            job_location_state:
                              nullable: true
                              example: null
                            job_started_on:
                              type: string
                              example: Sep 2023
                            job_still_working:
                              type: boolean
                              example: true
                            job_title:
                              type: string
                              example: CIO Procurement - Finance - CSR
                            raw_company_name:
                              type: string
                              example: ENGIE
                            raw_job_title:
                              type: string
                              example: CIO Procurement - Finance - CSR
                        example:
                          - company_city: null
                            company_country: France
                            company_description: |-
                              ENGIE is a global reference in low-carbon energy and services. With its 97,000 employees, clients, partners and stakeholders, the Group strives every day to accelerate the transition towards a carbon-neutral economy, through reduced energy consumption and more environmentally friendly solutions. Inspired by its purpose statement, ENGIE reconciles economic performance with a positive impact on people and the planet, building on its key businesses (gas, renewable energy, services) to offer competitive solutions to its clients. 

                              We are a united group, committed to inclusiveness and diversity, where everyone can forge their own career path , improve on their skills, and continually enhance their expertise. We work in a caring, flexible, and secure environment that encourages personal and professional development. #WithENGIE 


                              Turnover in 2023: EUR82.6 billion. The Group is listed on the Paris and Brussels stock exchanges (ENGI) and is represented in the main financial indices (CAC 40, Euronext 100, FTSE Euro 100, MSCI Europe) and non-financial indices (DJSI World, Euronext Vigeo Eiris - Europe 120 / France 20, MSCI EMU ESG screened, MSCI EUROPE ESG Universal Select, Stoxx Europe 600 ESG-X).
                            company_headcount_range: 10001+
                            company_id: '298246'
                            company_image: https://media.licdn.com/dms/image/v2/C4D0BAQHQn5EB4SKDyg/company-logo_400_400/company-logo_400_400/0/1630570629615/engie_logo?e=1741219200&v=beta&t=-Ga4LKJPrvzQnNm3PuUG9lkHYwO4IRP1R79TgqSeftc
                            company_industry: Utilities
                            company_location: France
                            company_name: ENGIE
                            company_state: ''
                            company_url: https://www.linkedin.com/company/engie/
                            company_website: https://www.engie.com/en
                            job_description: null
                            job_ended_on: null
                            job_location: Paris et peripherie
                            job_location_city: null
                            job_location_country: Ethiopia
                            job_location_county: null
                            job_location_state: null
                            job_started_on: Sep 2023
                            job_still_working: true
                            job_title: CIO Procurement - Finance - CSR
                            raw_company_name: ENGIE
                            raw_job_title: CIO Procurement - Finance - CSR
                      languages:
                        type: array
                        items: {}
                        example: []
                      last_name:
                        type: string
                        example: Traoré
                      linkedin_id:
                        type: string
                        example: '113966911'
                      linkedin_sales_link:
                        type: string
                        example: https://www.linkedin.com/sales/lead/ACwAAAbK_z8BitOI-5PxZa_jkG05STRmNLRaK14,NAME_SEARCH,OJWs
                      linkedin_url:
                        type: string
                        example: https://www.linkedin.com/in/birama-traor%C3%A9
                      location:
                        type: string
                        example: Greater Paris Metropolitan Region
                      location_city:
                        type: string
                        example: ''
                      location_country:
                        type: string
                        example: France
                      location_county:
                        nullable: true
                        example: null
                      location_state:
                        type: string
                        example: Ile-de-France
                      middle_name:
                        type: string
                        example: ''
                      num_of_connections:
                        type: number
                        example: 2253
                      private_website:
                        nullable: true
                        example: null
                      profile_photo:
                        type: string
                        example: https://media.licdn.com/dms/image/v2/C4D03AQFUuSLnGkiKVA/profile-displayphoto-shrink_800_800/profile-displayphoto-shrink_800_800/0/1625575996700?e=1738800000&v=beta&t=y0ZfbWCCWzmJOHFim2Y5_MSDchOztFjtsqbP61ze_EU
                      raw_company_name:
                        type: string
                        example: ENGIE
                      raw_headline:
                        type: string
                        example: CIO Procurement - Finance - CSR
                      raw_job_title:
                        type: string
                        example: CIO Procurement - Finance - CSR
                      sales_id:
                        type: string
                        example: ACwAAAbK_z8BitOI-5PxZa_jkG05STRmNLRaK14
                      skills:
                        type: array
                        items: {}
                        example: []
                      source:
                        type: string
                        example: lead_by_link
                      summary:
                        type: string
                        example: |-
                          I have been working in the Information Technology for the last 15 years. I have occupied different consultancy and management roles within the value chain, ranging from Infrastructure ones to transformation lead ones. In these roles I had the privilege to directly manage highly-skilled teams up to 80 people across 5 different geographies. I have managed business IT operations, process and transformation projects.

                          3 years ago, I joined ENGIE IT as the Head of Enterprise Service Management with notably two major programs in my scope: The Salesforce & Service Now Center Of Excellence - Both initiatives aims to help our client to achieve exponential growth. 

                          My best contributions are in transformation environments, where we have to lead our teams through changes in business models and culture. I do believe in leadership by example and I like to enable teams and clients to grow and achieve goals they did not think possible.

                          My current topics consist of setting up powerful Center of Excellence in order to foster expertise and take it to the next level of the organization in terms of business objectives & value. The goal is to lead transformation and enhance expertise to serve business growth.
                      twitter_link:
                        nullable: true
                        example: null
                      unformatted_full_name:
                        type: string
                        example: Birama Traoré
              examples:
                '200':
                  value:
                    amount: -1
                    lead:
                      certifications: []
                      company_city: null
                      company_country: France
                      company_description: |-
                        ENGIE is a global reference in low-carbon energy and services. With its 97,000 employees, clients, partners and stakeholders, the Group strives every day to accelerate the transition towards a carbon-neutral economy, through reduced energy consumption and more environmentally friendly solutions. Inspired by its purpose statement, ENGIE reconciles economic performance with a positive impact on people and the planet, building on its key businesses (gas, renewable energy, services) to offer competitive solutions to its clients. 

                        We are a united group, committed to inclusiveness and diversity, where everyone can forge their own career path , improve on their skills, and continually enhance their expertise. We work in a caring, flexible, and secure environment that encourages personal and professional development. #WithENGIE 


                        Turnover in 2023: EUR82.6 billion. The Group is listed on the Paris and Brussels stock exchanges (ENGI) and is represented in the main financial indices (CAC 40, Euronext 100, FTSE Euro 100, MSCI Europe) and non-financial indices (DJSI World, Euronext Vigeo Eiris - Europe 120 / France 20, MSCI EMU ESG screened, MSCI EUROPE ESG Universal Select, Stoxx Europe 600 ESG-X).
                      company_headcount_range: 10001+
                      company_id: '298246'
                      company_image: https://media.licdn.com/dms/image/v2/C4D0BAQHQn5EB4SKDyg/company-logo_400_400/company-logo_400_400/0/1630570629615/engie_logo?e=1741219200&v=beta&t=-Ga4LKJPrvzQnNm3PuUG9lkHYwO4IRP1R79TgqSeftc
                      company_industry: Utilities
                      company_location: France
                      company_name: ENGIE
                      company_state: ''
                      company_url: https://www.linkedin.com/company/engie/
                      company_website: https://www.engie.com/en
                      educations:
                        - degree: Certificat de formation generale (CFG)
                          ended_on:
                            month: 5
                            year: 2023
                          fields_of_study: null
                          started_on:
                            month: 3
                            year: 2023
                          university_id: '14803'
                          university_name: CentraleSupelec
                        - degree: Ingenieur
                          ended_on:
                            year: 2007
                          fields_of_study:
                            - Systeme et Reseau
                          started_on:
                            year: 2002
                          university_id: null
                          university_name: EITI
                        - degree: Certification EasyVista
                          ended_on: null
                          fields_of_study: null
                          started_on:
                            year: 2013
                          university_id: null
                          university_name: EasyVista
                        - degree: Certification HP SM 9
                          ended_on: null
                          fields_of_study: null
                          started_on:
                            year: 2012
                          university_id: null
                          university_name: HP
                        - degree: Certification ITIL V2
                          ended_on: null
                          fields_of_study: null
                          started_on:
                            year: 2012
                          university_id: null
                          university_name: ITIL
                      first_name: Birama
                      full_name: Birama Traoré
                      headline: CIO Procurement - Finance - CSR
                      industry: IT Services and IT Consulting
                      input_url: https://www.linkedin.com/in/birama-traor%c3%a9/
                      is_full_data: true
                      is_job_seeker: false
                      is_openlink: false
                      is_premium: false
                      is_retired: false
                      job_description: null
                      job_ended_on: null
                      job_location: Paris et peripherie
                      job_location_city: null
                      job_location_country: Ethiopia
                      job_location_county: null
                      job_location_state: null
                      job_started_on: Sep 2023
                      job_still_working: true
                      job_title: CIO Procurement - Finance - CSR
                      jobs:
                        - company_city: null
                          company_country: France
                          company_description: |-
                            ENGIE is a global reference in low-carbon energy and services. With its 97,000 employees, clients, partners and stakeholders, the Group strives every day to accelerate the transition towards a carbon-neutral economy, through reduced energy consumption and more environmentally friendly solutions. Inspired by its purpose statement, ENGIE reconciles economic performance with a positive impact on people and the planet, building on its key businesses (gas, renewable energy, services) to offer competitive solutions to its clients. 

                            We are a united group, committed to inclusiveness and diversity, where everyone can forge their own career path , improve on their skills, and continually enhance their expertise. We work in a caring, flexible, and secure environment that encourages personal and professional development. #WithENGIE 


                            Turnover in 2023: EUR82.6 billion. The Group is listed on the Paris and Brussels stock exchanges (ENGI) and is represented in the main financial indices (CAC 40, Euronext 100, FTSE Euro 100, MSCI Europe) and non-financial indices (DJSI World, Euronext Vigeo Eiris - Europe 120 / France 20, MSCI EMU ESG screened, MSCI EUROPE ESG Universal Select, Stoxx Europe 600 ESG-X).
                          company_headcount_range: 10001+
                          company_id: '298246'
                          company_image: https://media.licdn.com/dms/image/v2/C4D0BAQHQn5EB4SKDyg/company-logo_400_400/company-logo_400_400/0/1630570629615/engie_logo?e=1741219200&v=beta&t=-Ga4LKJPrvzQnNm3PuUG9lkHYwO4IRP1R79TgqSeftc
                          company_industry: Utilities
                          company_location: France
                          company_name: ENGIE
                          company_state: ''
                          company_url: https://www.linkedin.com/company/engie/
                          company_website: https://www.engie.com/en
                          job_description: null
                          job_ended_on: null
                          job_location: Paris et peripherie
                          job_location_city: null
                          job_location_country: Ethiopia
                          job_location_county: null
                          job_location_state: null
                          job_started_on: Sep 2023
                          job_still_working: true
                          job_title: CIO Procurement - Finance - CSR
                          raw_company_name: ENGIE
                          raw_job_title: CIO Procurement - Finance - CSR
                      languages: []
                      last_name: Traoré
                      linkedin_id: '113966911'
                      linkedin_sales_link: https://www.linkedin.com/sales/lead/ACwAAAbK_z8BitOI-5PxZa_jkG05STRmNLRaK14,NAME_SEARCH,OJWs
                      linkedin_url: https://www.linkedin.com/in/birama-traor%C3%A9
                      location: Greater Paris Metropolitan Region
                      location_city: ''
                      location_country: France
                      location_county: null
                      location_state: Ile-de-France
                      middle_name: ''
                      num_of_connections: 2253
                      private_website: null
                      profile_photo: https://media.licdn.com/dms/image/v2/C4D03AQFUuSLnGkiKVA/profile-displayphoto-shrink_800_800/profile-displayphoto-shrink_800_800/0/1625575996700?e=1738800000&v=beta&t=y0ZfbWCCWzmJOHFim2Y5_MSDchOztFjtsqbP61ze_EU
                      raw_company_name: ENGIE
                      raw_headline: CIO Procurement - Finance - CSR
                      raw_job_title: CIO Procurement - Finance - CSR
                      sales_id: ACwAAAbK_z8BitOI-5PxZa_jkG05STRmNLRaK14
                      skills: []
                      source: lead_by_link
                      summary: |-
                        I have been working in the Information Technology for the last 15 years. I have occupied different consultancy and management roles within the value chain, ranging from Infrastructure ones to transformation lead ones. In these roles I had the privilege to directly manage highly-skilled teams up to 80 people across 5 different geographies. I have managed business IT operations, process and transformation projects.

                        3 years ago, I joined ENGIE IT as the Head of Enterprise Service Management with notably two major programs in my scope: The Salesforce & Service Now Center Of Excellence - Both initiatives aims to help our client to achieve exponential growth. 

                        My best contributions are in transformation environments, where we have to lead our teams through changes in business models and culture. I do believe in leadership by example and I like to enable teams and clients to grow and achieve goals they did not think possible.

                        My current topics consist of setting up powerful Center of Excellence in order to foster expertise and take it to the next level of the organization in terms of business objectives & value. The goal is to lead transformation and enhance expertise to serve business growth.
                      twitter_link: null
                      unformatted_full_name: Birama Traoré
        '400':
          description: 400 (Bad url)
          headers:
            Allow:
              schema:
                type: string
                example: POST, OPTIONS
            Content-Length:
              schema:
                type: string
                example: '128'
            Cross-Origin-Opener-Policy:
              schema:
                type: string
                example: same-origin
            Date:
              schema:
                type: string
                example: Mon, 02 Dec 2024 20:07:43 GMT
            Referrer-Policy:
              schema:
                type: string
                example: same-origin
            Server:
              schema:
                type: string
                example: WSGIServer/0.2 CPython/3.11.10
            Vary:
              schema:
                type: string
                example: Accept, Origin
            X-Content-Type-Options:
              schema:
                type: string
                example: nosniff
            X-Frame-Options:
              schema:
                type: string
                example: DENY
          content:
            application/json:
              schema:
                type: object
                properties:
                  amount:
                    type: number
                    example: 0
                  detail:
                    type: string
                    example: Bad url
                  input_url:
                    type: string
                    example: https://www.facebook.com/in/birama-traor%c3%a9/
                  status:
                    type: string
                    example: error
                  status_code:
                    type: number
                    example: 400
              examples:
                400 (Bad url):
                  value:
                    amount: 0
                    detail: Bad url
                    input_url: https://www.facebook.com/in/birama-traor%c3%a9/
                    status: error
                    status_code: 400
        '401':
          description: '401'
          headers:
            Allow:
              schema:
                type: string
                example: POST, OPTIONS
            Content-Length:
              schema:
                type: string
                example: '94'
            Cross-Origin-Opener-Policy:
              schema:
                type: string
                example: same-origin
            Date:
              schema:
                type: string
                example: Mon, 02 Dec 2024 19:58:56 GMT
            Referrer-Policy:
              schema:
                type: string
                example: same-origin
            Server:
              schema:
                type: string
                example: WSGIServer/0.2 CPython/3.11.10
            Vary:
              schema:
                type: string
                example: Accept, Origin
            WWW-Authenticate:
              schema:
                type: string
                example: Token
            X-Content-Type-Options:
              schema:
                type: string
                example: nosniff
            X-Frame-Options:
              schema:
                type: string
                example: DENY
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: Invalid token header. No credentials provided.
                  status:
                    type: string
                    example: error
                  status_code:
                    type: number
                    example: 401
              examples:
                '401':
                  value:
                    detail: Invalid token header. No credentials provided.
                    status: error
                    status_code: 401
  /api/linkedin/leads/by_icp/:
    post:
      deprecated: true
      tags:
        - 3. Leads
      summary: Get List of Leads by ICP
      description: Search for leads based on your Ideal Customer Profile (ICP). Retrieve leads by criteria or from specified companies.
      operationId: getListOfLeadsByIcp
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                company_link:
                  type: string
                  description: "Use 'company_link' or 'company_id'. One of them is required"
                company_id:
                  type: integer
                  description: "Optional."
                locations:
                  type: array
                  items:
                    type: string
                personas:
                  type: array
                  items:
                    type: array
                    items:
                      oneOf:
                        - type: string
                        - type: array
                          items:
                            type: string
                    minItems: 4
                limit_by:
                  type: integer
                exclude_names:
                  type: array
                  items:
                    type: string
                exclude_ids:
                  type: array
                  items:
                    type: string
                  description: "Optional, list of sales_id values to exclude from results."
                filter_empty_vars:
                  type: array
                  items:
                    type: string
                changed_jobs:
                  type: boolean
                  description: "Optional, flag to specify if jobs have changed."
                posted_on_linkedin:
                  type: boolean
                  description: "Optional, flag to specify if posted on LinkedIn."
                mentioned_in_news:
                  type: boolean
                  description: "Optional, flag to specify if mentioned in news."
                lead_industries:
                  type: array
                  items:
                    type: string
                  description: "Optional, list of industries."
                company_locations:
                  type: array
                  items:
                    type: string
                  description: "Optional, company locations."
                company_headcounts:
                  type: array
                  items:
                    type: string
                  description: "Optional, company headcounts."
                company_types:
                  type: array
                  items:
                    type: string
                  description: "Optional, company types."
                past_company_names:
                  type: array
                  items:
                    type: string
                  description: "Optional, list of past company names."
                years_in_company:
                  type: array
                  items:
                    type: integer
                  description: "Optional, number of years in a company."
                years_in_position:
                  type: array
                  items:
                    type: integer
                  description: "Optional, number of years in the position."
                groups:
                  type: array
                  items:
                    type: integer
                  description: "Optional, list of group IDs."
                schools:
                  type: array
                  items:
                    type: integer
                  description: "Optional, list of school IDs."
                linkedin_filter_link:
                  type: string
                  description: "Optional, pre-built LinkedIn search URL (Sales Navigator or regular search) containing search filters."
                without_company:
                  type: boolean
                  description: "Optional, set to true to search leads across all companies without company restriction."

            examples:
              Get List of Leads by ICP:
                value:
                  company_link: https://www.linkedin.com/company/slack-technologies
                  locations:
                    - "San Francisco, California, United States"
                    - "New York, New York, United States"
                    - "London, England, United Kingdom"
                  personas:
                    - - "Marketing Leaders"
                      - - "marketing"
                        - "digital marketing"
                        - "growth"
                        - "demand generation"
                        - "brand"
                      - - "Director"
                        - "VP"
                        - "Head"
                        - "Manager"
                      - - "intern"
                        - "coordinator"
                        - "specialist"
                        - "associate"
                    - - "Sales Executives"
                      - - "sales"
                        - "business development"
                        - "revenue"
                        - "enterprise sales"
                        - "account management"
                      - - "VP"
                        - "Director"
                        - "Head"
                        - "Manager"
                      - - "representative"
                        - "coordinator"
                        - "intern"
                        - "junior"
                    - - "Product Managers"
                      - - "product"
                        - "product management"
                        - "product marketing"
                        - "product strategy"
                        - "product operations"
                      - - "VP"
                        - "Director"
                        - "Head"
                        - "Senior"
                      - - "analyst"
                        - "coordinator"
                        - "intern"
                        - "associate"
                  limit_by: 50
                  exclude_names:
                    - "John Smith"
                    - "Sarah Johnson" 
                    - "Michael Brown"
                    - "Emily Davis"
                    - "David Wilson"
                    - "Jennifer Garcia"
                  filter_empty_vars:
                    - "job_started_on"
                    - "profile_photo"
              Get List of Leads using LinkedIn Filter Link:
                value:
                  linkedin_filter_link: "https://www.linkedin.com/sales/search/people?query=(spellCorrectionEnabled%3Atrue%2Ckeywords%3Amarketing%2CfirstName%3A%2ClastName%3A%2Ctitle%3A%2Ccompany%3A%2Cschool%3A%2CcontactInterest%3A%2CnetworkDepth%3A%2Clanguage%3A%2Clocation%3A%2Cindustry%3A%2CcurrentCompany%3A%2CpastCompany%3A%2CprofileLanguage%3A%2CnonprofitInterest%3A%2CfortuneOrGlobal500Size%3A%2CsalesPersona%3A)"
                  limit_by: 100
              Get List of Leads by Company Name:
                value:
                  company_name: "Microsoft"
                  personas:
                    - - "Marketing"
                      - - "marketing"
                        - "digital marketing"
                      - []
                      - []
                  limit_by: 50
              Get List of Leads by Lead Criteria Only:
                value:
                  without_company: true
                  locations:
                    - "New York, New York, United States"
                  personas:
                    - - "Tech Leaders"
                      - - "CTO"
                        - "VP Engineering"
                        - "Tech Director"
                      - - "VP"
                        - "Director"
                      - []
                  limit_by: 100
      responses:
        '200':
          description: 200 / 200 (Leads not found)
          headers:
            Allow:
              schema:
                type: string
                example: POST, OPTIONS
            Content-Length:
              schema:
                type: string
                example: '70'
            Cross-Origin-Opener-Policy:
              schema:
                type: string
                example: same-origin
            Date:
              schema:
                type: string
                example: Mon, 02 Dec 2024 21:10:37 GMT
            Referrer-Policy:
              schema:
                type: string
                example: same-origin
            Server:
              schema:
                type: string
                example: WSGIServer/0.2 CPython/3.11.10
            Vary:
              schema:
                type: string
                example: Accept, Origin
            X-Content-Type-Options:
              schema:
                type: string
                example: nosniff
            X-Frame-Options:
              schema:
                type: string
                example: DENY
          content:
            application/json:
              schema:
                type: object
                properties:
                  amount:
                    type: number
                    example: -1
                  leads:
                    type: array
                    items:
                      type: object
                      properties:
                        certifications:
                          type: array
                          items: {}
                          example: []
                        company_city:
                          type: string
                          example: Schwarzenbek
                        company_country:
                          type: string
                          example: Germany
                        company_description:
                          type: string
                          example: Slack is a business communication platform offering persistent workplace chat, private groups, direct messaging, file sharing, and application integration.
                        company_headcount_range:
                          type: string
                          example: 501-1000
                        company_id:
                          type: string
                          example: '7590254'
                        company_image:
                          type: string
                          example: https://media.licdn.com/dms/image/v2/D4E0BAQEuyU0O4IbVRQ/company-logo_200_200/company-logo_200_200/0/1720783130887/fette_compacting_gmbh_logo?e=1740009600&v=beta&t=jP_aJALpJhdsmjNIpbePqKkzUyp1-Qno9lWH9eV9g9M
                        company_industry:
                          type: string
                          example: Pharmaceutical Manufacturing
                        company_location:
                          type: string
                          example: Schwarzenbek, Schleswig-Holstein, Germany
                        company_name:
                          type: string
                          example: Slack
                        company_state:
                          type: string
                          example: Schleswig-Holstein
                        company_url:
                          nullable: true
                          example: null
                        company_website:
                          type: string
                          example: http://www.fette-compacting.com
                        educations:
                          type: array
                          items: {}
                          example: []
                        first_name:
                          type: string
                          example: Sarah
                        full_name:
                          type: string
                          example: Sarah Chen
                        headline:
                          type: string
                          example: Senior Marketing Director at Slack
                        industry:
                          type: string
                          example: Machinery Manufacturing
                        is_full_data:
                          type: boolean
                          example: true
                        is_job_seeker:
                          type: boolean
                          example: false
                        is_openlink:
                          type: boolean
                          example: false
                        is_premium:
                          type: boolean
                          example: false
                        is_retired:
                          type: boolean
                          example: false
                        job_description:
                          type: string
                          example: 'Conception, elaboration and further development of the global communication strategy (media, budget) as a basis for decision-making for the management. Advising global management on communication issues such as change processes. Coordination, control and implementation of the communication strategy process: putting together international project teams, participating in the communication strategy process as an expert/adviser, writing speeches, specialist articles, press releases, etc., controlling editorial activities, expanding press work, further developing and implementing employer branding activities. www.fette-compacting.com'
                        job_ended_on:
                          nullable: true
                          example: null
                        job_location:
                          type: string
                          example: Schwarzenbek, Schleswig-Holstein, Deutschland
                        job_started_on:
                          type: string
                          example: Mar 2023
                        job_still_working:
                          type: boolean
                          example: true
                        job_title:
                          type: string
                          example: Senior Marketing Director
                        jobs:
                          type: array
                          items:
                            type: object
                            properties:
                              company_city:
                                type: string
                                example: Cincinnati
                              company_country:
                                type: string
                                example: United States
                              company_description:
                                type: string
                                example: ART WORKS IN ANDERSON LLC is a retail company based out of 1115 MAYCLIFFE PL, Cincinnati, Ohio, United States.
                              company_headcount_range:
                                type: string
                                example: 11-50
                              company_id:
                                type: string
                                example: '63587704'
                              company_image:
                                type: string
                                nullable: true
                                example: null
                              company_industry:
                                type: string
                                example: Retail
                              company_location:
                                type: string
                                example: Cincinnati, Ohio, United States
                              company_name:
                                type: string
                                example: Anderson Art Work / Self-employed
                              company_state:
                                type: string
                                example: Ohio
                              company_url:
                                type: string
                                example: https://www.linkedin.com/company/art-works-in-anderson-llc/
                              company_website:
                                type: string
                                example: http://cincinnatiartclasses.com
                              job_description:
                                type: string
                                example: |-
                                  http://www.andersonartwork.de/
                                  https://www.facebook.com/AndersonArtWork.de
                                  http://instagram.com/nicoleandersonartwork 
                                  http://www.pinterest.com/AndersonAW/
                              job_ended_on:
                                nullable: true
                                example: null
                              job_location:
                                type: string
                                example: Hamburg und Umgebung, Deutschland
                              job_started_on:
                                type: string
                                example: '2013'
                              job_still_working:
                                type: boolean
                                example: true
                              job_title:
                                type: string
                                example: Freelance Artist
                              raw_company_name:
                                type: string
                                example: Anderson Art Work / Self-employed
                              raw_job_title:
                                type: string
                                example: Freelance Artist
                          example:
                            - company_city: Cincinnati
                              company_country: United States
                              company_description: ART WORKS IN ANDERSON LLC is a retail company based out of 1115 MAYCLIFFE PL, Cincinnati, Ohio, United States.
                              company_headcount_range: 11-50
                              company_id: '63587704'
                              company_image: null
                              company_industry: Retail
                              company_location: Cincinnati, Ohio, United States
                              company_name: Anderson Art Work / Self-employed
                              company_state: Ohio
                              company_url: https://www.linkedin.com/company/art-works-in-anderson-llc/
                              company_website: http://cincinnatiartclasses.com
                              job_description: |-
                                http://www.andersonartwork.de/
                                https://www.facebook.com/AndersonArtWork.de
                                http://instagram.com/nicoleandersonartwork 
                                http://www.pinterest.com/AndersonAW/
                              job_ended_on: null
                              job_location: Hamburg und Umgebung, Deutschland
                              job_started_on: '2013'
                              job_still_working: true
                              job_title: Freelance Artist
                              raw_company_name: Anderson Art Work / Self-employed
                              raw_job_title: Freelance Artist
                            - company_city: San Francisco
                              company_country: United States
                              company_description: Fette Compacting is the world's leading provider of integrated solutions for industrial tablet production.
                              company_headcount_range: 501-1000
                              company_id: '21828'
                              company_image: https://media.licdn.com/dms/image/v2/D4E0BAQEuyU0O4IbVRQ/company-logo_400_400/company-logo_400_400/0/1720783130887/fette_compacting_gmbh_logo?e=1741219200&v=beta&t=HvwsgIyJYXepYTbSz8ySstMn8d3F9LgQtRtqEeLdqKI
                              company_industry: Software Development
                              company_location: San Francisco, California, United States
                              company_name: Slack
                              company_state: California
                              company_url: https://www.linkedin.com/company/slack-technologies/
                              company_website: https://slack.com
                              job_description: 'Lead global marketing strategy and demand generation programs to drive customer acquisition and retention. Oversee brand positioning, content marketing, and digital campaigns across all channels. Collaborate with product, sales, and growth teams to accelerate user adoption and revenue growth. Manage marketing budget allocation and performance metrics to optimize ROI and scale marketing operations globally.'
                              job_ended_on: null
                              job_location: San Francisco, California, United States
                              job_started_on: Mar 2023
                              job_still_working: true
                              job_title: Senior Marketing Director
                              raw_company_name: Slack
                              raw_job_title: Senior Marketing Director
                        languages:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                                example: Englisch
                              proficiency:
                                type: string
                                example: FULL_PROFESSIONAL
                          example:
                            - name: Englisch
                              proficiency: FULL_PROFESSIONAL
                            - name: Deutsch
                              proficiency: NATIVE_OR_BILINGUAL
                        last_name:
                          type: string
                          example: Anderson
                        linkedin_company_id:
                          type: string
                          example: '7590254'
                        linkedin_id:
                          type: string
                          example: '80282110'
                        linkedin_lead_persona:
                          type: string
                          example: Marketing Leaders
                        linkedin_sales_link:
                          type: string
                          example: https://www.linkedin.com/sales/lead/ACwAAATJAf4BWNxU442ZgFSJw2zzlmG6S3zv-e0,NAME_SEARCH,OJWs
                        linkedin_url:
                          type: string
                          example: https://www.linkedin.com/in/nicole-anderson-profile
                        location:
                          type: string
                          example: San Francisco, California, United States
                        location_city:
                          nullable: true
                          example: null
                        location_country:
                          type: string
                          example: Germany
                        location_county:
                          nullable: true
                          example: null
                        location_state:
                          type: string
                          example: Hamburg
                        middle_name:
                          type: string
                          example: ''
                        num_of_connections:
                          type: number
                          example: 710
                        private_website:
                          nullable: true
                          example: null
                        profile_photo:
                          type: string
                          example: https://media.licdn.com/dms/image/v2/D4D03AQHdu7xNE9zgIw/profile-displayphoto-shrink_800_800/profile-displayphoto-shrink_800_800/0/1724341778966?e=1738800000&v=beta&t=bEH4zW5MrIkRknwhvnOX5GQYRUOlIg9jib4wpsEWahE
                        raw_company_name:
                          type: string
                          example: Slack
                        raw_headline:
                          type: string
                          example: Senior Marketing Director at Slack
                        raw_job_title:
                          type: string
                          example: Senior Marketing Director
                        sales_id:
                          type: string
                          example: ACwAAATJAf4BWNxU442ZgFSJw2zzlmG6S3zv-e0
                        skills:
                          type: array
                          items: {}
                          example: []
                        summary:
                          type: string
                          example: |-
                            Experienced marketing leader with 8+ years driving growth for B2B SaaS companies. Expert in demand generation, content marketing, and marketing automation platforms. Proven track record of scaling marketing operations from startup to IPO, including leading marketing teams of 20+ professionals. Specialized in product marketing, customer lifecycle campaigns, and conversion optimization.

                            Passionate about data-driven marketing, emerging technologies, and building high-performing teams.
                        twitter_link:
                          nullable: true
                          example: null
                        unformatted_full_name:
                          type: string
                          example: Sarah Chen
                    example:
                      - certifications: []
                        company_city: San Francisco
                        company_country: United States
                        company_description: Fette Compacting is the world's leading provider of integrated solutions for industrial tablet production.
                        company_headcount_range: 501-1000
                        company_id: '21828'
                        company_image: https://media.licdn.com/dms/image/v2/D4E0BAQEuyU0O4IbVRQ/company-logo_200_200/company-logo_200_200/0/1720783130887/fette_compacting_gmbh_logo?e=1740009600&v=beta&t=jP_aJALpJhdsmjNIpbePqKkzUyp1-Qno9lWH9eV9g9M
                        company_industry: Software Development
                        company_location: San Francisco, California, United States
                        company_name: Slack
                        company_state: California
                        company_url: null
                        company_website: https://slack.com
                        educations: []
                        first_name: Sarah
                        full_name: Sarah Chen
                        headline: Senior Marketing Director at Slack
                        industry: Software Development
                        is_full_data: true
                        is_job_seeker: false
                        is_openlink: false
                        is_premium: false
                        is_retired: false
                        job_description: 'Lead global marketing strategy and demand generation programs to drive customer acquisition and retention. Oversee brand positioning, content marketing, and digital campaigns across all channels. Collaborate with product, sales, and growth teams to accelerate user adoption and revenue growth. Manage marketing budget allocation and performance metrics to optimize ROI and scale marketing operations globally.'
                        job_ended_on: null
                        job_location: San Francisco, California, United States
                        job_started_on: Mar 2023
                        job_still_working: true
                        job_title: Senior Marketing Director
                        jobs:
                          - company_city: Cincinnati
                            company_country: United States
                            company_description: ART WORKS IN ANDERSON LLC is a retail company based out of 1115 MAYCLIFFE PL, Cincinnati, Ohio, United States.
                            company_headcount_range: 11-50
                            company_id: '63587704'
                            company_image: null
                            company_industry: Retail
                            company_location: Cincinnati, Ohio, United States
                            company_name: Anderson Art Work / Self-employed
                            company_state: Ohio
                            company_url: https://www.linkedin.com/company/art-works-in-anderson-llc/
                            company_website: http://cincinnatiartclasses.com
                            job_description: |-
                              http://www.andersonartwork.de/
                              https://www.facebook.com/AndersonArtWork.de
                              http://instagram.com/nicoleandersonartwork 
                              http://www.pinterest.com/AndersonAW/
                            job_ended_on: null
                            job_location: Hamburg und Umgebung, Deutschland
                            job_started_on: '2013'
                            job_still_working: true
                            job_title: Freelance Artist
                            raw_company_name: Anderson Art Work / Self-employed
                            raw_job_title: Freelance Artist
                          - company_city: San Francisco
                            company_country: United States
                            company_description: Fette Compacting is the world's leading provider of integrated solutions for industrial tablet production.
                            company_headcount_range: 501-1000
                            company_id: '21828'
                            company_image: https://media.licdn.com/dms/image/v2/D4E0BAQEuyU0O4IbVRQ/company-logo_400_400/company-logo_400_400/0/1720783130887/fette_compacting_gmbh_logo?e=1741219200&v=beta&t=HvwsgIyJYXepYTbSz8ySstMn8d3F9LgQtRtqEeLdqKI
                            company_industry: Software Development
                            company_location: San Francisco, California, United States
                            company_name: Slack
                            company_state: California
                            company_url: https://www.linkedin.com/company/slack-technologies/
                            company_website: https://slack.com
                            job_description: 'Lead global marketing strategy and demand generation programs to drive customer acquisition and retention. Oversee brand positioning, content marketing, and digital campaigns across all channels. Collaborate with product, sales, and growth teams to accelerate user adoption and revenue growth. Manage marketing budget allocation and performance metrics to optimize ROI and scale marketing operations globally.'
                            job_ended_on: null
                            job_location: San Francisco, California, United States
                            job_started_on: Mar 2023
                            job_still_working: true
                            job_title: Senior Marketing Director
                            raw_company_name: Slack
                            raw_job_title: Senior Marketing Director
                        languages:
                          - name: Englisch
                            proficiency: FULL_PROFESSIONAL
                          - name: Deutsch
                            proficiency: NATIVE_OR_BILINGUAL
                        last_name: Anderson
                        linkedin_company_id: '21828'
                        linkedin_id: '80282110'
                        linkedin_lead_persona: Marketing Leaders
                        linkedin_sales_link: https://www.linkedin.com/sales/lead/ACwAAATJAf4BWNxU442ZgFSJw2zzlmG6S3zv-e0,NAME_SEARCH,OJWs
                        linkedin_url: https://www.linkedin.com/in/sarah-chen-marketing
                        location: San Francisco, California, United States
                        location_city: null
                        location_country: United States
                        location_county: null
                        location_state: California
                        middle_name: ''
                        num_of_connections: 710
                        private_website: null
                        profile_photo: https://media.licdn.com/dms/image/v2/D4D03AQHdu7xNE9zgIw/profile-displayphoto-shrink_800_800/profile-displayphoto-shrink_800_800/0/1724341778966?e=1738800000&v=beta&t=bEH4zW5MrIkRknwhvnOX5GQYRUOlIg9jib4wpsEWahE
                        raw_company_name: Slack
                        raw_headline: Senior Marketing Director at Slack
                        raw_job_title: Senior Marketing Director
                        sales_id: ACwAAATJAf4BWNxU442ZgFSJw2zzlmG6S3zv-e0
                        skills: []
                        summary: |-
                          Experienced marketing leader with 8+ years driving growth for B2B SaaS companies. Expert in demand generation, content marketing, and marketing automation platforms. Proven track record of scaling marketing operations from startup to IPO, including leading marketing teams of 20+ professionals. Specialized in product marketing, customer lifecycle campaigns, and conversion optimization.

                          Passionate about data-driven marketing, emerging technologies, and building high-performing teams.
                        twitter_link: null
                        unformatted_full_name: Sarah Chen
                  results_count:
                    type: string
                    example: within limit
                  status:
                    type: string
                    example: No leads match with input criteria
              examples:
                '200':
                  value:
                    amount: -1
                    leads:
                      - certifications: []
                        company_city: San Francisco
                        company_country: United States
                        company_description: Fette Compacting is the world's leading provider of integrated solutions for industrial tablet production.
                        company_headcount_range: 501-1000
                        company_id: '21828'
                        company_image: https://media.licdn.com/dms/image/v2/D4E0BAQEuyU0O4IbVRQ/company-logo_200_200/company-logo_200_200/0/1720783130887/fette_compacting_gmbh_logo?e=1740009600&v=beta&t=jP_aJALpJhdsmjNIpbePqKkzUyp1-Qno9lWH9eV9g9M
                        company_industry: Software Development
                        company_location: San Francisco, California, United States
                        company_name: Slack
                        company_state: California
                        company_url: null
                        company_website: https://slack.com
                        educations: []
                        first_name: Sarah
                        full_name: Sarah Chen
                        headline: Senior Marketing Director at Slack
                        industry: Software Development
                        is_full_data: true
                        is_job_seeker: false
                        is_openlink: false
                        is_premium: false
                        is_retired: false
                        job_description: 'Lead global marketing strategy and demand generation programs to drive customer acquisition and retention. Oversee brand positioning, content marketing, and digital campaigns across all channels. Collaborate with product, sales, and growth teams to accelerate user adoption and revenue growth. Manage marketing budget allocation and performance metrics to optimize ROI and scale marketing operations globally.'
                        job_ended_on: null
                        job_location: San Francisco, California, United States
                        job_started_on: Mar 2023
                        job_still_working: true
                        job_title: Senior Marketing Director
                        jobs:
                          - company_city: Cincinnati
                            company_country: United States
                            company_description: ART WORKS IN ANDERSON LLC is a retail company based out of 1115 MAYCLIFFE PL, Cincinnati, Ohio, United States.
                            company_headcount_range: 11-50
                            company_id: '63587704'
                            company_image: null
                            company_industry: Retail
                            company_location: Cincinnati, Ohio, United States
                            company_name: Anderson Art Work / Self-employed
                            company_state: Ohio
                            company_url: https://www.linkedin.com/company/art-works-in-anderson-llc/
                            company_website: http://cincinnatiartclasses.com
                            job_description: |-
                              http://www.andersonartwork.de/
                              https://www.facebook.com/AndersonArtWork.de
                              http://instagram.com/nicoleandersonartwork 
                              http://www.pinterest.com/AndersonAW/
                            job_ended_on: null
                            job_location: Hamburg und Umgebung, Deutschland
                            job_started_on: '2013'
                            job_still_working: true
                            job_title: Freelance Artist
                            raw_company_name: Anderson Art Work / Self-employed
                            raw_job_title: Freelance Artist
                          - company_city: San Francisco
                            company_country: United States
                            company_description: Fette Compacting is the world's leading provider of integrated solutions for industrial tablet production.
                            company_headcount_range: 501-1000
                            company_id: '21828'
                            company_image: https://media.licdn.com/dms/image/v2/D4E0BAQEuyU0O4IbVRQ/company-logo_400_400/company-logo_400_400/0/1720783130887/fette_compacting_gmbh_logo?e=1741219200&v=beta&t=HvwsgIyJYXepYTbSz8ySstMn8d3F9LgQtRtqEeLdqKI
                            company_industry: Software Development
                            company_location: San Francisco, California, United States
                            company_name: Slack
                            company_state: California
                            company_url: https://www.linkedin.com/company/slack-technologies/
                            company_website: https://slack.com
                            job_description: 'Lead global marketing strategy and demand generation programs to drive customer acquisition and retention. Oversee brand positioning, content marketing, and digital campaigns across all channels. Collaborate with product, sales, and growth teams to accelerate user adoption and revenue growth. Manage marketing budget allocation and performance metrics to optimize ROI and scale marketing operations globally.'
                            job_ended_on: null
                            job_location: San Francisco, California, United States
                            job_started_on: Mar 2023
                            job_still_working: true
                            job_title: Senior Marketing Director
                            raw_company_name: Slack
                            raw_job_title: Senior Marketing Director
                        languages:
                          - name: Englisch
                            proficiency: FULL_PROFESSIONAL
                          - name: Deutsch
                            proficiency: NATIVE_OR_BILINGUAL
                        last_name: Anderson
                        linkedin_company_id: '21828'
                        linkedin_id: '80282110'
                        linkedin_lead_persona: Marketing Leaders
                        linkedin_sales_link: https://www.linkedin.com/sales/lead/ACwAAATJAf4BWNxU442ZgFSJw2zzlmG6S3zv-e0,NAME_SEARCH,OJWs
                        linkedin_url: https://www.linkedin.com/in/sarah-chen-marketing
                        location: San Francisco, California, United States
                        location_city: null
                        location_country: United States
                        location_county: null
                        location_state: California
                        middle_name: ''
                        num_of_connections: 710
                        private_website: null
                        profile_photo: https://media.licdn.com/dms/image/v2/D4D03AQHdu7xNE9zgIw/profile-displayphoto-shrink_800_800/profile-displayphoto-shrink_800_800/0/1724341778966?e=1738800000&v=beta&t=bEH4zW5MrIkRknwhvnOX5GQYRUOlIg9jib4wpsEWahE
                        raw_company_name: Slack
                        raw_headline: Senior Marketing Director at Slack
                        raw_job_title: Senior Marketing Director
                        sales_id: ACwAAATJAf4BWNxU442ZgFSJw2zzlmG6S3zv-e0
                        skills: []
                        summary: |-
                          Experienced marketing leader with 8+ years driving growth for B2B SaaS companies. Expert in demand generation, content marketing, and marketing automation platforms. Proven track record of scaling marketing operations from startup to IPO, including leading marketing teams of 20+ professionals. Specialized in product marketing, customer lifecycle campaigns, and conversion optimization.

                          Passionate about data-driven marketing, emerging technologies, and building high-performing teams.
                        twitter_link: null
                        unformatted_full_name: Sarah Chen
                    results_count: within limit
                200 (Leads not found):
                  value:
                    amount: -1
                    leads: []
                    status: No leads match with input criteria
  /api/linkedin/leads/by_icp/get_count/:
    post:
      deprecated: true
      tags:
        - 3. Leads
      summary: Count leads by ICP
      description:  Estimate the number of leads matching specific search criteria.
      operationId: countLeadsByIcp
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                company_link:
                  type: string
                  description: "Use 'company_link' or 'company_id'. One of them is required."
                company_id:
                  type: integer
                  description: "Optional"
                locations:
                  type: array
                  items:
                    type: string
                personas:
                  type: array
                  items:
                    type: array
                    items:
                      oneOf:
                        - type: string
                        - type: array
                          items:
                            type: string
                    minItems: 4
                exclude_names:
                  type: array
                  items:
                    type: string
                filter_empty_vars:
                  type: array
                  items:
                    type: string
                changed_jobs:
                  type: boolean
                  description: "Optional, flag to specify if jobs have changed."
                posted_on_linkedin:
                  type: boolean
                  description: "Optional, flag to specify if posted on LinkedIn."
                mentioned_in_news:
                  type: boolean
                  description: "Optional, flag to specify if mentioned in news."
                lead_industries:
                  type: array
                  items:
                    type: string
                  description: "Optional, list of industries"
                company_locations:
                  type: array
                  items:
                    type: string
                  description: "Optional, company locations."
                company_headcounts:
                  type: array
                  items:
                    type: string
                  description: "Optional, company headcounts."
                company_types:
                  type: array
                  items:
                    type: string
                  description: "Optional, company types."
                past_company_names:
                  type: array
                  items:
                    type: string
                  description: "Optional, list of past company names."
                years_in_company:
                  type: array
                  items:
                    type: integer
                  description: "Optional, number of years in a company."
                years_in_position:
                  type: array
                  items:
                    type: integer
                  description: "Optional, number of years in the position."
                groups:
                  type: array
                  items:
                    type: integer
                  description: "Optional, list of group IDs."
                schools:
                  type: array
                  items:
                    type: integer
                  description: "Optional, list of school IDs."

            examples:
              Get List of Leads by ICP:
                value:
                  company_link: https://www.linkedin.com/company/fette-compacting-gmbh
                  locations:
                    - Austria
                    - Switzerland
                  personas:
                    - - Communication
                      - - Communication
                        - Kommunikation
                        - Communication
                      - []
                      - - Assistant
                        - Operations
                        - Hubspot
                    - - Communications
                      - - Communications
                        - Kommunikation
                        - Communications
                      - []
                      - - Assistant
                        - Operations
                        - Hubspot
                  exclude_names:
                    - Volker Reinsch
                    - Nathalie Hoffmann
                    - Nora Behrens
                    - Emanuel da Silva Gomes
                    - Kerstin Schaper
                    - Angela Hogrefe
                  filter_empty_vars:
                    - started_at_position
      responses:
        '200':
          description: '200'
          headers:
            Allow:
              schema:
                type: string
                example: POST, OPTIONS
            Content-Length:
              schema:
                type: string
                example: '44'
            Cross-Origin-Opener-Policy:
              schema:
                type: string
                example: same-origin
            Date:
              schema:
                type: string
                example: Mon, 02 Dec 2024 21:38:18 GMT
            Referrer-Policy:
              schema:
                type: string
                example: same-origin
            Server:
              schema:
                type: string
                example: WSGIServer/0.2 CPython/3.11.10
            Vary:
              schema:
                type: string
                example: Accept, Origin
            X-Content-Type-Options:
              schema:
                type: string
                example: nosniff
            X-Frame-Options:
              schema:
                type: string
                example: DENY
          content:
            application/json:
              schema:
                type: object
                properties:
                  amount:
                    type: number
                    example: -3
                  results_count:
                    type: string
                    example: within limit
              examples:
                '200':
                  value:
                    amount: -3
                    results_count: within limit
      security:
        - apiKey: []
  /api/linkedin/companies/by_link/:
    post:
      tags:
        - 4. Companies
      summary: Get Company by link
      description: Enrich or update your database with detailed company information from a provided URL, domain or company name.
      operationId: getCompanyByLink
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                people_also_viewed:
                  type: boolean
                  description: Include people also viewed data (+1 credit)
                people_also_follow:
                  type: boolean
                posts:
                  type: boolean
                  description: Include posts data (+1 credit)
              required:
              - url
              - people_also_viewed
              - people_also_follow
              - posts

            examples:
              Get Company by link:
                value:
                  url: https://www.linkedin.com/company/a2-aprende-y-aplica-capacitaciГіn
                  people_also_viewed: true
                  people_also_follow: false
                  posts: true
      responses:
        '200':
          description: '200'
          headers:
            Allow:
              schema:
                type: string
                example: POST, OPTIONS
            Content-Length:
              schema:
                type: string
                example: '1918'
            Cross-Origin-Opener-Policy:
              schema:
                type: string
                example: same-origin
            Date:
              schema:
                type: string
                example: Mon, 02 Dec 2024 21:55:14 GMT
            Referrer-Policy:
              schema:
                type: string
                example: same-origin
            Server:
              schema:
                type: string
                example: WSGIServer/0.2 CPython/3.11.10
            Vary:
              schema:
                type: string
                example: Accept, Origin
            X-Content-Type-Options:
              schema:
                type: string
                example: nosniff
            X-Frame-Options:
              schema:
                type: string
                example: DENY
            djdt-store-id:
              schema:
                type: string
                example: 31890c37311043a089c11732738015df
          content:
            application/json:
              schema:
                type: object
                properties:
                  amount:
                    type: number
                    example: -1
                  company:
                    type: object
                    properties:
                      background_image:
                        type: string
                        example: https://media.licdn.com/dms/image/v2/C561BAQG9Ktb_CKMogA/company-background_10000/company-background_10000/0/1585429294192/a2_aprende_y_aplica_capacitacin_cover?e=1733781600&v=beta&t=Ob5IiQY2u18mTXsF8DXY3zI2rYoPhYGX5gG_EWJeams
                      company_type:
                        type: string
                        example: Educational
                      crunchbase_urn:
                        nullable: true
                        example: null
                      default_locale:
                        type: string
                        example: es
                      description:
                        type: string
                        example: "La mision de A2 es hacer de la capacitacion en las empresas el principal motor de la productividad de su gente.\r\n\r\nCreemos que una capacitacion no solo debe de consistir de un simple curso, sino que el curso debe de ser parte de un proceso mas grande que resulte en mejoras de procedmientos, correccion de errores e innovacion interna."
                      domain:
                        type: string
                        example: a2capacitacion.com
                      founded_year:
                        type: number
                        example: 2009
                      groups:
                        type: array
                        items: {}
                        example: []
                      hashtags:
                        type: array
                        items:
                          type: string
                          example: spreadsheets
                        example:
                          - spreadsheets
                          - spreadsheet
                          - microsoftexcel
                      headcount_exact:
                        type: number
                        example: 14
                      headcount_range:
                        type: string
                        example: 1-10
                      hq_additional_info:
                        type: string
                        example: La Estancia
                      hq_city:
                        type: string
                        example: Zapopan
                      hq_country:
                        type: string
                        example: Mexico
                      hq_country_code:
                        type: string
                        example: MX
                      hq_postal_code:
                        type: string
                        example: '45030'
                      hq_state:
                        type: string
                        example: Jalisco
                      hq_street:
                        type: string
                        example: Hector Berlioz 5691
                      industry:
                        type: string
                        example: Education Management
                      is_claimable:
                        type: boolean
                        example: false
                      linkedin_id:
                        type: string
                        example: '10403092'
                      linkedin_link:
                        type: string
                        example: https://www.linkedin.com/company/a2-aprende-y-aplica-capacitaci-n/
                      linkedin_urn:
                        type: string
                        example: a2-aprende-y-aplica-capacitaci-n
                      location:
                        type: string
                        example: Zapopan, Jalisco, Mexico
                      logo_url:
                        type: string
                        example: https://media.licdn.com/dms/image/v2/D560BAQGn4NkVFt7_cw/company-logo_200_200/company-logo_200_200/0/1712690269654/a2_aprende_y_aplica_capacitacin_logo?e=1741219200&v=beta&t=fCAoQ1xShF-4JtIpqUahalzYnHDEUUttqNG0CyByF3o
                      name:
                        type: string
                        example: A2 Aprende y Aplica Capacitacion
                      number_of_locations:
                        type: number
                        example: 1
                      other_locations_json:
                        type: array
                        items: {}
                        example: []
                      phone_number:
                        nullable: true
                        example: null
                      raw_name:
                        type: string
                        example: A2 Aprende y Aplica Capacitación
                      showcase_pages:
                        nullable: true
                        example: null
                      source:
                        type: string
                        example: company_by_link
                      specialities:
                        type: array
                        items:
                          type: string
                          example: Capacitacion
                        example:
                          - Capacitacion
                          - Consultoria en Educacion
                          - Diseno de Materiales Educativos
                          - Excel
                      tagline:
                        type: string
                        example: |
                          Haz Magia con Excel
                      website:
                        type: string
                        example: http://www.a2capacitacion.com
              examples:
                '200':
                  value:
                    amount: -1
                    company:
                      background_image: https://media.licdn.com/dms/image/v2/C561BAQG9Ktb_CKMogA/company-background_10000/company-background_10000/0/1585429294192/a2_aprende_y_aplica_capacitacin_cover?e=1733781600&v=beta&t=Ob5IiQY2u18mTXsF8DXY3zI2rYoPhYGX5gG_EWJeams
                      company_type: Educational
                      crunchbase_urn: null
                      default_locale: es
                      description: "La mision de A2 es hacer de la capacitacion en las empresas el principal motor de la productividad de su gente.\r\n\r\nCreemos que una capacitacion no solo debe de consistir de un simple curso, sino que el curso debe de ser parte de un proceso mas grande que resulte en mejoras de procedmientos, correccion de errores e innovacion interna."
                      domain: a2capacitacion.com
                      founded_year: 2009
                      groups: []
                      hashtags:
                        - spreadsheets
                        - spreadsheet
                        - microsoftexcel
                      headcount_exact: 14
                      headcount_range: 1-10
                      hq_additional_info: La Estancia
                      hq_city: Zapopan
                      hq_country: Mexico
                      hq_country_code: MX
                      hq_postal_code: '45030'
                      hq_state: Jalisco
                      hq_street: Hector Berlioz 5691
                      industry: Education Management
                      is_claimable: false
                      linkedin_id: '10403092'
                      linkedin_link: https://www.linkedin.com/company/a2-aprende-y-aplica-capacitaci-n/
                      linkedin_urn: a2-aprende-y-aplica-capacitaci-n
                      location: Zapopan, Jalisco, Mexico
                      logo_url: https://media.licdn.com/dms/image/v2/D560BAQGn4NkVFt7_cw/company-logo_200_200/company-logo_200_200/0/1712690269654/a2_aprende_y_aplica_capacitacin_logo?e=1741219200&v=beta&t=fCAoQ1xShF-4JtIpqUahalzYnHDEUUttqNG0CyByF3o
                      name: A2 Aprende y Aplica Capacitacion
                      number_of_locations: 1
                      other_locations_json: []
                      phone_number: null
                      raw_name: A2 Aprende y Aplica Capacitación
                      showcase_pages: null
                      source: company_by_link
                      specialities:
                        - Capacitacion
                        - Consultoria en Educacion
                        - Diseno de Materiales Educativos
                        - Excel
                      tagline: |
                        Haz Magia con Excel
                      website: http://www.a2capacitacion.com
        '400':
          description: 400 (Bad url)
          headers:
            Allow:
              schema:
                type: string
                example: POST, OPTIONS
            Content-Length:
              schema:
                type: string
                example: '147'
            Cross-Origin-Opener-Policy:
              schema:
                type: string
                example: same-origin
            Date:
              schema:
                type: string
                example: Mon, 02 Dec 2024 21:55:47 GMT
            Referrer-Policy:
              schema:
                type: string
                example: same-origin
            Server:
              schema:
                type: string
                example: WSGIServer/0.2 CPython/3.11.10
            Vary:
              schema:
                type: string
                example: Accept, Origin
            X-Content-Type-Options:
              schema:
                type: string
                example: nosniff
            X-Frame-Options:
              schema:
                type: string
                example: DENY
            djdt-store-id:
              schema:
                type: string
                example: 0450519dba5f40beb0cb3c6e778dac29
          content:
            application/json:
              schema:
                type: object
                properties:
                  amount:
                    type: number
                    example: 0
                  detail:
                    type: string
                    example: Bad url
                  input_url:
                    type: string
                    example: https://www.facebook.com/company/a2-aprende-y-aplica-capacitación
                  status:
                    type: string
                    example: error
                  status_code:
                    type: number
                    example: 400
              examples:
                400 (Bad url):
                  value:
                    amount: 0
                    detail: Bad url
                    input_url: https://www.facebook.com/company/a2-aprende-y-aplica-capacitación
                    status: error
                    status_code: 400
      security:
        - apiKey: []
  /api/linkedin/companies/by_icp/:
    post:
      deprecated: true
      tags:
        - 4. Companies
      summary: Get List of Companies by ICP
      description: Search for companies matching your ICP criteria, such as location, industry, revenue and more.
      operationId: getListOfCompaniesByIcp
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                company_types:
                  type: array
                  items:
                    type: string
                    example: Public Company
                  example:
                    - Public Company
                    - Self Employed
                    - Self Owned
                    - Privately Held
                    - Partnership
                get_max_companies:
                  type: boolean
                  example: true
                headcounts:
                  type: array
                  items:
                    type: string
                    example: 201-500
                  example:
                    - 201-500
                industries:
                  type: array
                  items:
                    type: string
                    example: Software Development
                  example:
                    - Software Development
                keywords:
                  type: array
                  items:
                    type: string
                    example: platform
                  example:
                    - platform
                    - marketplace
                limit_by:
                  type: number
                  example: 3
                locations:
                  type: array
                  items:
                    type: string
                    example: United States
                  example:
                    - United States
                num_of_followers:
                  type: array
                  items:
                    type: string
                    example: 5001+
                  example:
                    - 5001+
                offset_by:
                  type: number
                  example: 0
                revenues_range:
                  type: object
                  properties:
                    max:
                      type: number
                      example: 1
                    min:
                      type: number
                      example: 0
                sub_industries:
                  type: boolean
                  default: false
                  description: >-
                    By default (`false`) a selected industry also matches
                    companies in its sub-industries. Set to `true` to match only
                    the industries you specify and exclude their sub-industries —
                    for example, "Manufacturing" without "Chemicals".
                website_blacklist:
                  type: boolean
                  example: false
            examples:
              Get List of Companies by ICP:
                value:
                  company_types:
                    - Public Company
                    - Self Employed
                    - Self Owned
                    - Privately Held
                    - Partnership
                  get_max_companies: true
                  headcounts:
                    - 201-500
                  industries:
                    - Software Development
                  keywords:
                    - platform
                    - marketplace
                  limit_by: 3
                  locations:
                    - United States
                  num_of_followers:
                    - 5001+
                  offset_by: 0
                  revenues_range:
                    max: 1
                    min: 0
                  website_blacklist: false
      responses:
        '200':
          description: 200 / 200 (Companies not found)
          headers:
            Allow:
              schema:
                type: string
                example: POST, OPTIONS
            Content-Length:
              schema:
                type: string
                example: '88'
            Cross-Origin-Opener-Policy:
              schema:
                type: string
                example: same-origin
            Date:
              schema:
                type: string
                example: Mon, 02 Dec 2024 22:18:01 GMT
            Referrer-Policy:
              schema:
                type: string
                example: same-origin
            Server:
              schema:
                type: string
                example: WSGIServer/0.2 CPython/3.11.10
            Server-Timing:
              schema:
                type: string
                example: TimerPanel_utime;dur=432.78699999996206;desc="User CPU time", TimerPanel_stime;dur=165.48099999999977;desc="System CPU time", TimerPanel_total;dur=598.2679999999618;desc="Total CPU time", TimerPanel_total_time;dur=6539.156198501587;desc="Elapsed time", SQLPanel_sql_time;dur=104.11524772644043;desc="SQL 61 queries", CachePanel_total_time;dur=0;desc="Cache 0 Calls"
            Vary:
              schema:
                type: string
                example: Accept, Origin
            X-Content-Type-Options:
              schema:
                type: string
                example: nosniff
            X-Frame-Options:
              schema:
                type: string
                example: DENY
            djdt-store-id:
              schema:
                type: string
                example: 1ff04b8b7f2e46fe8719a56c58b38f64
          content:
            application/json:
              schema:
                type: object
                properties:
                  amount:
                    type: number
                    example: -3
                  companies:
                    type: array
                    items:
                      type: object
                      properties:
                        background_image:
                          type: string
                          example: https://media.licdn.com/dms/image/v2/D561BAQH-LSq7Ba0bIw/company-background_10000/company-background_10000/0/1661361722654/platform_science_cover?e=1733781600&v=beta&t=nNQUFM5YTQNAeH2xQ4IN1g00oUwIxL6LmP-80VJrB2g
                        company_type:
                          type: string
                          example: Privately Held
                        crunchbase_urn:
                          type: string
                          example: platform-science
                        description:
                          type: string
                          example: |-
                            Since 2015, Platform Science has connected fleets across the nation with the tools they need to take control of their technology. As part of our ongoing mission to transform transportation, we've made it easy for fleets to develop, deploy, and manage their commercial vehicles' mobile devices and applications on a single platform.


                            Through our partnerships with industry leaders at every stage of 
                            the supply chain, we empower fleets with endless opportunities to innovate and create solutions that evolve as their businesses grow.
                        domain:
                          type: string
                          example: platformscience.com
                        founded_year:
                          type: number
                          nullable: true
                          example: 2015
                        hashtags:
                          type: array
                          items:
                            type: string
                            example: innovation
                          example:
                            - innovation
                            - platformscience
                            - trucking
                        headcount_exact:
                          type: number
                          example: 307
                        headcount_range:
                          type: string
                          example: 201-500
                        hq_additional_info:
                          type: string
                          nullable: true
                          example: Ste 100
                        hq_city:
                          type: string
                          example: San Diego
                        hq_country:
                          type: string
                          example: United States
                        hq_country_code:
                          type: string
                          example: US
                        hq_postal_code:
                          type: string
                          nullable: true
                          example: '92121'
                        hq_state:
                          type: string
                          nullable: true
                          example: California
                        hq_street:
                          type: string
                          example: 9620 Towne Centre Dr
                        industry:
                          type: string
                          example: Software Development
                        linkedin_id:
                          type: string
                          example: '18000638'
                        linkedin_link:
                          type: string
                          example: https://www.linkedin.com/company/platform-science/
                        linkedin_sales_link:
                          type: string
                          example: https://www.linkedin.com/sales/company/18000638/
                        linkedin_urn:
                          type: string
                          example: platform-science
                        location:
                          type: string
                          example: San Diego, California, United States
                        logo_url:
                          type: string
                          example: https://media.licdn.com/dms/image/v2/C560BAQFwDh5F4FjKSg/company-logo_200_200/company-logo_200_200/0/1630640177343/platform_science_logo?e=1741219200&v=beta&t=15yZwQUYLQyFiNhVZJIA6c0RoW1pmh4SgbwrIt3DTaU
                        name:
                          type: string
                          example: Platform Science
                        number_of_locations:
                          type: number
                          example: 1
                        other_locations_json:
                          type: array
                          items: {}
                          example: []
                        phone_number:
                          nullable: true
                          example: null
                        raw_name:
                          type: string
                          example: Platform Science
                        specialities:
                          type: array
                          items: {}
                          example: []
                        tagline:
                          type: string
                          example: Making it easy for enterprise trucking fleets to develop, deploy, and manage mobile devices and applications.
                        website:
                          type: string
                          example: http://www.platformscience.com
                    example:
                      - background_image: https://media.licdn.com/dms/image/v2/D561BAQH-LSq7Ba0bIw/company-background_10000/company-background_10000/0/1661361722654/platform_science_cover?e=1733781600&v=beta&t=nNQUFM5YTQNAeH2xQ4IN1g00oUwIxL6LmP-80VJrB2g
                        company_type: Privately Held
                        crunchbase_urn: platform-science
                        description: |-
                          Since 2015, Platform Science has connected fleets across the nation with the tools they need to take control of their technology. As part of our ongoing mission to transform transportation, we've made it easy for fleets to develop, deploy, and manage their commercial vehicles' mobile devices and applications on a single platform.


                          Through our partnerships with industry leaders at every stage of 
                          the supply chain, we empower fleets with endless opportunities to innovate and create solutions that evolve as their businesses grow.
                        domain: platformscience.com
                        founded_year: 2015
                        hashtags:
                          - innovation
                          - platformscience
                          - trucking
                        headcount_exact: 307
                        headcount_range: 201-500
                        hq_additional_info: Ste 100
                        hq_city: San Diego
                        hq_country: United States
                        hq_country_code: US
                        hq_postal_code: '92121'
                        hq_state: California
                        hq_street: 9620 Towne Centre Dr
                        industry: Software Development
                        linkedin_id: '18000638'
                        linkedin_link: https://www.linkedin.com/company/platform-science/
                        linkedin_sales_link: https://www.linkedin.com/sales/company/18000638/
                        linkedin_urn: platform-science
                        location: San Diego, California, United States
                        logo_url: https://media.licdn.com/dms/image/v2/C560BAQFwDh5F4FjKSg/company-logo_200_200/company-logo_200_200/0/1630640177343/platform_science_logo?e=1741219200&v=beta&t=15yZwQUYLQyFiNhVZJIA6c0RoW1pmh4SgbwrIt3DTaU
                        name: Platform Science
                        number_of_locations: 1
                        other_locations_json: []
                        phone_number: null
                        raw_name: Platform Science
                        specialities: []
                        tagline: Making it easy for enterprise trucking fleets to develop, deploy, and manage mobile devices and applications.
                        website: http://www.platformscience.com
                      - background_image: https://media.licdn.com/dms/image/v2/C4E1BAQGQDeszLg8-bQ/company-background_10000/company-background_10000/0/1584798432532/pivotal_software_inc_cover?e=1733781600&v=beta&t=po2KejTkWo6n4wTKKFdcq2PJ5_0BO3LtGDH8NTa-psk
                        company_type: Public Company
                        crunchbase_urn: pivotal
                        description: 'VMware Tanzu helps you modernize your applications and infrastructure with a common goal: deliver better software to production, continuously. The portfolio simplifies multi-cloud operations, while freeing developers to move faster and access the right resources for building the best applications. VMware Tanzu enables development and operations'' teams to work together in new ways that deliver transformative business results.'
                        domain: vmware.com
                        founded_year: null
                        hashtags: []
                        headcount_exact: 271
                        headcount_range: 1001-5000
                        hq_additional_info: Fifth Floor
                        hq_city: San Francisco
                        hq_country: United States
                        hq_country_code: US
                        hq_postal_code: '94103'
                        hq_state: California
                        hq_street: 875 Howard Street
                        industry: Software Development
                        linkedin_id: '3048967'
                        linkedin_link: https://www.linkedin.com/company/pivotal-software-inc./
                        linkedin_sales_link: https://www.linkedin.com/sales/company/3048967/
                        linkedin_urn: pivotal-software-inc.
                        location: San Francisco, California, United States
                        logo_url: https://media.licdn.com/dms/image/v2/C560BAQEDUiaAXDr9tQ/company-logo_200_200/company-logo_200_200/0/1630621022655/pivotal_software_inc_logo?e=1741219200&v=beta&t=ZjLtQx9D3dr7nCau3PRRer33CUnUvl1i16hQTnBPiIk
                        name: Pivotal Software
                        number_of_locations: 13
                        other_locations_json:
                          - additional_info: Sixth Floor
                            city: New York
                            country: United States
                            description: New York
                            postal_code: 10011-2020
                            state: New York
                            street: 636 Avenue of the Americas
                          - additional_info: null
                            city: Toronto
                            country: Canada
                            description: Toronto
                            postal_code: M5C 2V6
                            state: Ontario
                            street: 1 Toronto Street Suite 1100
                          - additional_info: Second Floor
                            city: London
                            country: United Kingdom
                            description: London
                            postal_code: 'EC1V 9NR '
                            state: London
                            street: The Warehouse, 211 Old Street
                          - additional_info: null
                            city: Denver
                            country: United States
                            description: Denver
                            postal_code: '80202'
                            state: CO
                            street: 1644 Platte St
                          - additional_info: Suite 7500
                            city: Atlanta
                            country: United States
                            description: Atlanta
                            postal_code: '30308'
                            state: GA
                            street: '675 Ponce de Leon Avenue NE '
                          - additional_info: Level 16
                            city: Singapore
                            country: Singapore
                            description: Singapore
                            postal_code: '068907'
                            state: Singapore
                            street: 140 Robinson Road
                          - additional_info: Suite 1305
                            city: Chicago
                            country: United States
                            description: Chicago
                            postal_code: '60654'
                            state: Illinois
                            street: 222 W Merchandise Mart Plaza
                          - additional_info: null
                            city: Dallas
                            country: United States
                            description: Dallas
                            postal_code: null
                            state: Texas
                            street: 3001 Hackberry Rd
                          - additional_info: Suite 200
                            city: Santa Monica
                            country: United States
                            description: Los Angeles
                            postal_code: '90401'
                            state: California
                            street: 1333 2nd Street
                          - additional_info: Third Floor
                            city: Seattle
                            country: United States
                            description: Seattle
                            postal_code: '98104'
                            state: Washington
                            street: 111 S Jackson St
                          - additional_info: Suite 601
                            city: Washington, D.C.
                            country: United States
                            description: Washington, D.C.
                            postal_code: '20006'
                            state: DC
                            street: 1625 I St NW
                          - additional_info: Sixth Floor
                            city: Cambridge
                            country: United States
                            description: Cambridge
                            postal_code: '02142'
                            state: MA
                            street: 255 Main St
                        phone_number: null
                        raw_name: Pivotal Software, Inc.
                        specialities:
                          - big data
                          - cloud computing
                          - hadoop
                          - analytics
                          - software
                          - open source software
                          - containerization
                          - private cloud
                          - data science
                          - cloud foundry
                          - mobile software development
                          - platform-as-a-service
                          - hybrid cloud
                          - microservices
                          - pair programming
                          - agile development
                        tagline: 'We''ve moved! Follow us at VMware Tanzu: https://bit.ly/VMwareTanzuLinkedIn'
                        website: https://cloud.vmware.com/tanzu
                      - background_image: https://media.licdn.com/dms/image/v2/D4E1BAQHzLZJfSBt5-Q/company-background_10000/company-background_10000/0/1715298939407/kickstarter_cover?e=1733781600&v=beta&t=hlYd_IVSuB_24TF-wSqWWcUHUpjwoZ79rTLb-Ka4eis
                        company_type: Privately Held
                        crunchbase_urn: kickstarter
                        description: |-
                          Kickstarter helps creative projects come to life. Backers have pledged over $7B to projects on our platform, helping artists, musicians, filmmakers, designers, and other creators make their ideas a reality.

                          In 2022, we'll be experimenting with a work-from-anywhere policy, a four-day workweek, and new asynchronous work practices that support a fully virtual and flexible work environment. 
                            
                          Current job openings listed at jobs.kickstarter.com
                        domain: kck.st
                        founded_year: 2009
                        hashtags: []
                        headcount_exact: 340
                        headcount_range: 201-500
                        hq_additional_info: null
                        hq_city: Work From Anywhere
                        hq_country: United States
                        hq_country_code: US
                        hq_postal_code: null
                        hq_state: null
                        hq_street: Fully Virtual
                        industry: Software Development
                        linkedin_id: '413999'
                        linkedin_link: https://www.linkedin.com/company/kickstarter/
                        linkedin_sales_link: https://www.linkedin.com/sales/company/413999/
                        linkedin_urn: kickstarter
                        location: United States
                        logo_url: https://media.licdn.com/dms/image/v2/D560BAQGc1nYjgaNebw/company-logo_200_200/company-logo_200_200/0/1708024813718/kickstarter_logo?e=1741219200&v=beta&t=JP5QWgE_QQuHUvJLqdslb3h_OID-eBSJ8F2H9TuIZTU
                        name: Kickstarter
                        number_of_locations: 1
                        other_locations_json: []
                        phone_number: null
                        raw_name: Kickstarter
                        specialities: []
                        tagline: Bringing creative projects to life.
                        website: https://kck.st/3Gsc7QW
                  results_count:
                    type: number
                    example: 522
                  time_cached:
                    type: string
                    example: '2024-12-02T21:57:53.469659'
              examples:
                '200':
                  value:
                    amount: -3
                    companies:
                      - background_image: https://media.licdn.com/dms/image/v2/D561BAQH-LSq7Ba0bIw/company-background_10000/company-background_10000/0/1661361722654/platform_science_cover?e=1733781600&v=beta&t=nNQUFM5YTQNAeH2xQ4IN1g00oUwIxL6LmP-80VJrB2g
                        company_type: Privately Held
                        crunchbase_urn: platform-science
                        description: |-
                          Since 2015, Platform Science has connected fleets across the nation with the tools they need to take control of their technology. As part of our ongoing mission to transform transportation, we've made it easy for fleets to develop, deploy, and manage their commercial vehicles' mobile devices and applications on a single platform.


                          Through our partnerships with industry leaders at every stage of 
                          the supply chain, we empower fleets with endless opportunities to innovate and create solutions that evolve as their businesses grow.
                        domain: platformscience.com
                        founded_year: 2015
                        hashtags:
                          - innovation
                          - platformscience
                          - trucking
                        headcount_exact: 307
                        headcount_range: 201-500
                        hq_additional_info: Ste 100
                        hq_city: San Diego
                        hq_country: United States
                        hq_country_code: US
                        hq_postal_code: '92121'
                        hq_state: California
                        hq_street: 9620 Towne Centre Dr
                        industry: Software Development
                        linkedin_id: '18000638'
                        linkedin_link: https://www.linkedin.com/company/platform-science/
                        linkedin_sales_link: https://www.linkedin.com/sales/company/18000638/
                        linkedin_urn: platform-science
                        location: San Diego, California, United States
                        logo_url: https://media.licdn.com/dms/image/v2/C560BAQFwDh5F4FjKSg/company-logo_200_200/company-logo_200_200/0/1630640177343/platform_science_logo?e=1741219200&v=beta&t=15yZwQUYLQyFiNhVZJIA6c0RoW1pmh4SgbwrIt3DTaU
                        name: Platform Science
                        number_of_locations: 1
                        other_locations_json: []
                        phone_number: null
                        raw_name: Platform Science
                        specialities: []
                        tagline: Making it easy for enterprise trucking fleets to develop, deploy, and manage mobile devices and applications.
                        website: http://www.platformscience.com
                      - background_image: https://media.licdn.com/dms/image/v2/C4E1BAQGQDeszLg8-bQ/company-background_10000/company-background_10000/0/1584798432532/pivotal_software_inc_cover?e=1733781600&v=beta&t=po2KejTkWo6n4wTKKFdcq2PJ5_0BO3LtGDH8NTa-psk
                        company_type: Public Company
                        crunchbase_urn: pivotal
                        description: 'VMware Tanzu helps you modernize your applications and infrastructure with a common goal: deliver better software to production, continuously. The portfolio simplifies multi-cloud operations, while freeing developers to move faster and access the right resources for building the best applications. VMware Tanzu enables development and operations'' teams to work together in new ways that deliver transformative business results.'
                        domain: vmware.com
                        founded_year: null
                        hashtags: []
                        headcount_exact: 271
                        headcount_range: 1001-5000
                        hq_additional_info: Fifth Floor
                        hq_city: San Francisco
                        hq_country: United States
                        hq_country_code: US
                        hq_postal_code: '94103'
                        hq_state: California
                        hq_street: 875 Howard Street
                        industry: Software Development
                        linkedin_id: '3048967'
                        linkedin_link: https://www.linkedin.com/company/pivotal-software-inc./
                        linkedin_sales_link: https://www.linkedin.com/sales/company/3048967/
                        linkedin_urn: pivotal-software-inc.
                        location: San Francisco, California, United States
                        logo_url: https://media.licdn.com/dms/image/v2/C560BAQEDUiaAXDr9tQ/company-logo_200_200/company-logo_200_200/0/1630621022655/pivotal_software_inc_logo?e=1741219200&v=beta&t=ZjLtQx9D3dr7nCau3PRRer33CUnUvl1i16hQTnBPiIk
                        name: Pivotal Software
                        number_of_locations: 13
                        other_locations_json:
                          - additional_info: Sixth Floor
                            city: New York
                            country: United States
                            description: New York
                            postal_code: 10011-2020
                            state: New York
                            street: 636 Avenue of the Americas
                          - additional_info: null
                            city: Toronto
                            country: Canada
                            description: Toronto
                            postal_code: M5C 2V6
                            state: Ontario
                            street: 1 Toronto Street Suite 1100
                          - additional_info: Second Floor
                            city: London
                            country: United Kingdom
                            description: London
                            postal_code: 'EC1V 9NR '
                            state: London
                            street: The Warehouse, 211 Old Street
                          - additional_info: null
                            city: Denver
                            country: United States
                            description: Denver
                            postal_code: '80202'
                            state: CO
                            street: 1644 Platte St
                          - additional_info: Suite 7500
                            city: Atlanta
                            country: United States
                            description: Atlanta
                            postal_code: '30308'
                            state: GA
                            street: '675 Ponce de Leon Avenue NE '
                          - additional_info: Level 16
                            city: Singapore
                            country: Singapore
                            description: Singapore
                            postal_code: '068907'
                            state: Singapore
                            street: 140 Robinson Road
                          - additional_info: Suite 1305
                            city: Chicago
                            country: United States
                            description: Chicago
                            postal_code: '60654'
                            state: Illinois
                            street: 222 W Merchandise Mart Plaza
                          - additional_info: null
                            city: Dallas
                            country: United States
                            description: Dallas
                            postal_code: null
                            state: Texas
                            street: 3001 Hackberry Rd
                          - additional_info: Suite 200
                            city: Santa Monica
                            country: United States
                            description: Los Angeles
                            postal_code: '90401'
                            state: California
                            street: 1333 2nd Street
                          - additional_info: Third Floor
                            city: Seattle
                            country: United States
                            description: Seattle
                            postal_code: '98104'
                            state: Washington
                            street: 111 S Jackson St
                          - additional_info: Suite 601
                            city: Washington, D.C.
                            country: United States
                            description: Washington, D.C.
                            postal_code: '20006'
                            state: DC
                            street: 1625 I St NW
                          - additional_info: Sixth Floor
                            city: Cambridge
                            country: United States
                            description: Cambridge
                            postal_code: '02142'
                            state: MA
                            street: 255 Main St
                        phone_number: null
                        raw_name: Pivotal Software, Inc.
                        specialities:
                          - big data
                          - cloud computing
                          - hadoop
                          - analytics
                          - software
                          - open source software
                          - containerization
                          - private cloud
                          - data science
                          - cloud foundry
                          - mobile software development
                          - platform-as-a-service
                          - hybrid cloud
                          - microservices
                          - pair programming
                          - agile development
                        tagline: 'We''ve moved! Follow us at VMware Tanzu: https://bit.ly/VMwareTanzuLinkedIn'
                        website: https://cloud.vmware.com/tanzu
                      - background_image: https://media.licdn.com/dms/image/v2/D4E1BAQHzLZJfSBt5-Q/company-background_10000/company-background_10000/0/1715298939407/kickstarter_cover?e=1733781600&v=beta&t=hlYd_IVSuB_24TF-wSqWWcUHUpjwoZ79rTLb-Ka4eis
                        company_type: Privately Held
                        crunchbase_urn: kickstarter
                        description: |-
                          Kickstarter helps creative projects come to life. Backers have pledged over $7B to projects on our platform, helping artists, musicians, filmmakers, designers, and other creators make their ideas a reality.

                          In 2022, we'll be experimenting with a work-from-anywhere policy, a four-day workweek, and new asynchronous work practices that support a fully virtual and flexible work environment. 
                            
                          Current job openings listed at jobs.kickstarter.com
                        domain: kck.st
                        founded_year: 2009
                        hashtags: []
                        headcount_exact: 340
                        headcount_range: 201-500
                        hq_additional_info: null
                        hq_city: Work From Anywhere
                        hq_country: United States
                        hq_country_code: US
                        hq_postal_code: null
                        hq_state: null
                        hq_street: Fully Virtual
                        industry: Software Development
                        linkedin_id: '413999'
                        linkedin_link: https://www.linkedin.com/company/kickstarter/
                        linkedin_sales_link: https://www.linkedin.com/sales/company/413999/
                        linkedin_urn: kickstarter
                        location: United States
                        logo_url: https://media.licdn.com/dms/image/v2/D560BAQGc1nYjgaNebw/company-logo_200_200/company-logo_200_200/0/1708024813718/kickstarter_logo?e=1741219200&v=beta&t=JP5QWgE_QQuHUvJLqdslb3h_OID-eBSJ8F2H9TuIZTU
                        name: Kickstarter
                        number_of_locations: 1
                        other_locations_json: []
                        phone_number: null
                        raw_name: Kickstarter
                        specialities: []
                        tagline: Bringing creative projects to life.
                        website: https://kck.st/3Gsc7QW
                    results_count: 522
                    time_cached: '2024-12-02T21:57:53.469659'
                200 (Companies not found):
                  value:
                    amount: 0
                    companies: []
      security:
        - apiKey: []
  /api/linkedin/companies/by_icp/get_count/:
    post:
      deprecated: true
      tags:
        - 4. Companies
      summary: Count companies by ICP
      description: Estimate the number of companies matching specific search criteria.
      operationId: countCompaniesByIcp
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                get_max_companies:
                  type: boolean
                  example: true
                headcounts:
                  type: array
                  items:
                    type: string
                    example: 1-10
                  example:
                    - 1-10
                industries:
                  type: array
                  items:
                    type: string
                    example: Media Production
                  example:
                    - Media Production
                locations:
                  type: array
                  items:
                    type: string
                    example: Ontario, Canada
                  example:
                    - Ontario, Canada
                num_of_followers:
                  type: array
                  items:
                    type: string
                    example: 1-50
                  example:
                    - 1-50
                revenues_range:
                  type: object
                  properties:
                    max:
                      type: number
                      example: 5
                    min:
                      type: number
                      example: 1
            examples:
              Count companies by ICP:
                value:
                  get_max_companies: true
                  headcounts:
                    - 1-10
                  industries:
                    - Media Production
                  locations:
                    - Ontario, Canada
                  num_of_followers:
                    - 1-50
                  revenues_range:
                    max: 5
                    min: 1
      responses:
        '200':
          description: '200'
          headers:
            Allow:
              schema:
                type: string
                example: POST, OPTIONS
            Content-Length:
              schema:
                type: string
                example: '32'
            Cross-Origin-Opener-Policy:
              schema:
                type: string
                example: same-origin
            Date:
              schema:
                type: string
                example: Mon, 02 Dec 2024 22:19:04 GMT
            Referrer-Policy:
              schema:
                type: string
                example: same-origin
            Server:
              schema:
                type: string
                example: WSGIServer/0.2 CPython/3.11.10
            Vary:
              schema:
                type: string
                example: Accept, Origin
            X-Content-Type-Options:
              schema:
                type: string
                example: nosniff
            X-Frame-Options:
              schema:
                type: string
                example: DENY
          content:
            application/json:
              schema:
                type: object
                properties:
                  amount:
                    type: number
                    example: -1
                  results_count:
                    type: number
                    example: 46
              examples:
                '200':
                  value:
                    amount: -1
                    results_count: 46
      security:
        - apiKey: []
  /api/linkedin/email_finder/:
    post:
      summary: Generate valid email
      description: Generate and validate corporate email addresses using first name, last name, and domain. All generated emails are automatically validated and ready for use - no additional validation required.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  first_name:
                    type: string
                  last_name:
                    type: string
                  domain:
                    type: string
              example:
                - first_name: Jack
                  last_name: Kennedy
                  domain: platformscience.com
      responses:
        '200':
          description: Successful response with email details
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    first_name:
                      type: string
                    last_name:
                      type: string
                    domain:
                      type: string
                    result:
                      type: string
                    catch_all:
                      type: string
                    error:
                      type: string
                      nullable: true
                    valid_email:
                      type: string
                    source:
                      type: string
                    email_format:
                      type: string
                    mx_domain:
                      type: string
                    logs:
                      type: string
                    exist:
                      type: string
              example:
                - first_name: Jack
                  last_name: Kennedy
                  domain: platformscience.com
                  result: valid
                  catch_all: true
                  error: null
                  valid_email: jkennedy@platformscience.com
                  source: name2email
                  email_format: flast
                  mx_domain: pphosted.com
                  logs: "get mx_record: pphosted.com\ncheck outlook,gmail,onedrive,o365,o365_get_creds\n"
                  exist: yes

  /api/linkedin/email_validator/:
    post:
      summary: Validate an email address
      description: Validate email addresses for deliverability, including catch-all domains, using our proprietary system.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
              example:
                - jkennedy@platformscience.com
      responses:
        '200':
          description: Successful email validation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    result:
                      type: string
                    catch_all:
                      type: string
                    error:
                      type: string
                      nullable: true
                    source:
                      type: string
                    mx_domain:
                      type: string
                    exist:
                      type: string
                    email:
                      type: string
                    logs:
                      type: array
                      items:
                        type: string
              example:
                - result: valid
                  catch_all: true
                  error: null
                  source: name2email
                  mx_domain: pphosted.com
                  exist: yes
                  email: jkennedy@platformscience.com
                  logs:
                    - get mx_record: pphosted.com
                    - check outlook,gmail,onedrive,o365,o365_get_creds
  /api/v1/preview/leads/:
    post:
      tags:
        - 5. Preview
      summary: Preview leads
      description: Search database leads with masked response data. Preview results include an internal lead ID for later enrichment and do not include LinkedIn URL, company domain, email, or phone.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                company_search_criteria:
                  type: object
                  description: Company filters (same as /search/database/companies/).
                  properties:
                    industries:
                      type: array
                      items:
                        type: string
                    headcounts:
                      type: array
                      items:
                        type: string
                    locations:
                      type: array
                      items:
                        type: string
                    company_types:
                      type: array
                      items:
                        type: string
                lead_search_criteria:
                  type: object
                  description: Lead filters (same as /search/database/leads/).
                  properties:
                    job_titles:
                      type: array
                      items:
                        type: string
                    seniorities:
                      type: array
                      items:
                        type: string
                    locations:
                      type: array
                      items:
                        type: string
                    company_industries:
                      type: array
                      items:
                        type: string
                    company_headcounts:
                      type: array
                      items:
                        type: string
                    personas:
                      type: array
                      items:
                        type: array
                    limit_by:
                      type: integer
                    offset_by:
                      type: integer
            examples:
              Preview leads:
                value:
                  company_search_criteria:
                    industries:
                      - Software Development
                    headcounts:
                      - 51-200
                    locations:
                      - United States
                  lead_search_criteria:
                    job_titles:
                      - CEO
                      - Founder
                    seniorities:
                      - c_suite
                    locations:
                      - United States
                    limit_by: 25
      responses:
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"company_headcounts": ["Object with name=999 does not exist."]}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Account is not enabled for the Preview endpoint.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              example:
                error: You are not authorized to use this endpoint.
        '200':
          description: Masked lead preview results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewLeadsResponse'
              example:
                data:
                  leads:
                    - id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                      first_name: Jordan
                      last_name: Ellis
                      title: CEO
                      company_name: Microsoft
                      location: San Francisco, CA
                      industry: Software Development
                      seniority: CXO
                      headcount_range: 51-200
                    - id: ACwAAAFp2r4Bd1eF3gH5iJ7kL9mN0pQ2rS4tU6v
                      first_name: Morgan
                      last_name: Lee
                      title: VP Sales
                      company_name: Salesforce
                      location: New York, NY
                      industry: Software Development
                      seniority: VP
                      headcount_range: 201-500
                meta:
                  amount_charged: 0
  /api/v1/preview/leads/count/:
    post:
      tags:
        - 5. Preview
      summary: Count preview leads
      description: Count matching database leads for Preview. Count requests are always free.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                company_search_criteria:
                  type: object
                  description: Company filters (same as Preview leads).
                  properties:
                    industries:
                      type: array
                      items:
                        type: string
                    headcounts:
                      type: array
                      items:
                        type: string
                    locations:
                      type: array
                      items:
                        type: string
                lead_search_criteria:
                  type: object
                  description: Lead filters (same as Preview leads).
                  properties:
                    job_titles:
                      type: array
                      items:
                        type: string
                    seniorities:
                      type: array
                      items:
                        type: string
                    locations:
                      type: array
                      items:
                        type: string
                    company_industries:
                      type: array
                      items:
                        type: string
                    company_headcounts:
                      type: array
                      items:
                        type: string
            examples:
              Count preview leads:
                value:
                  company_search_criteria:
                    industries:
                      - Software Development
                    locations:
                      - United States
                  lead_search_criteria:
                    job_titles:
                      - CEO
                    locations:
                      - United States
      responses:
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"company_headcounts": ["Object with name=999 does not exist."]}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Account is not enabled for the Preview endpoint.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              example:
                error: You are not authorized to use this endpoint.
        '200':
          description: Matching lead count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewCountResponse'
              example:
                data:
                  count: 1240
                meta:
                  amount_charged: 0
  /api/v1/enrich/database/lead/:
    post:
      tags:
        - 6. Enrich
      summary: Enrich lead from database
      description: Retrieve a full lead profile from cached data. Provide exactly one identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - title: By Generect ID
                  type: object
                  required:
                    - id
                  properties:
                    id:
                      type: string
                      description: Internal Generect lead identifier returned by Search or Preview.
                      example: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                - title: By LinkedIn URL
                  type: object
                  required:
                    - linkedin_url
                  properties:
                    linkedin_url:
                      type: string
                      description: >
                        LinkedIn profile URL. Supported formats:
                        linkedin.com/in/{slug}, linkedin.com/in/{id} (e.g. AAW1Sghsd),
                        linkedin.com/sales/lead/{id},NAME_SEARCH,...
                      example: https://www.linkedin.com/in/jordan-ellis
                - title: By Email
                  type: object
                  required:
                    - email
                  properties:
                    email:
                      type: string
                      description: Work email address for reverse lookup.
                      example: jordan.ellis@microsoft.com
            examples:
              By Generect ID:
                value:
                  id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
              By LinkedIn URL:
                value:
                  linkedin_url: https://www.linkedin.com/in/jordan-ellis
              By email:
                value:
                  email: jordan.ellis@microsoft.com
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"fields": "exactly one of id, linkedin_url, email is required"}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '200':
          description: Full lead profile. If no data is found, the request is free.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichLeadResponse'
              example:
                data:
                  id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                  first_name: Jordan
                  last_name: Ellis
                  title: CEO
                  headline: CEO at Microsoft
                  linkedin_url: https://www.linkedin.com/in/jordan-ellis
                  location: San Francisco, CA
                  seniority: CXO
                  company:
                    id: 1035
                    name: Microsoft
                    domain: microsoft.com
                    linkedin_url: https://www.linkedin.com/company/microsoft/
                    industry: Software Development
                    headcount: 150
                  work_history: []
                  education: []
                  skills: []
                meta:
                  amount_charged: 0.02
  /api/v1/enrich/realtime/lead/:
    post:
      tags:
        - 6. Enrich
      summary: Enrich lead in realtime
      description: Retrieve a fresh lead profile. Supports internal ID, LinkedIn URL, or email reverse lookup. If no data is found, the request is free.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - title: By Generect ID
                  type: object
                  required:
                    - id
                  properties:
                    id:
                      type: string
                      description: Internal Generect lead identifier returned by Search or Preview.
                      example: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                - title: By LinkedIn URL
                  type: object
                  required:
                    - linkedin_url
                  properties:
                    linkedin_url:
                      type: string
                      description: >
                        LinkedIn profile URL. Supported formats:
                        linkedin.com/in/{slug}, linkedin.com/in/{id} (e.g. AAW1Sghsd),
                        linkedin.com/sales/lead/{id},NAME_SEARCH,...
                      example: https://www.linkedin.com/in/jordan-ellis
                - title: By Email
                  type: object
                  required:
                    - email
                  properties:
                    email:
                      type: string
                      description: Work email address for reverse lookup.
                      example: jordan.ellis@microsoft.com
            examples:
              By Generect ID:
                value:
                  id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
              By LinkedIn URL:
                value:
                  linkedin_url: https://www.linkedin.com/in/jordan-ellis
              By email (reverse lookup):
                value:
                  email: jordan.ellis@microsoft.com
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"fields": "exactly one of id, linkedin_url, email is required"}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '200':
          description: Fresh full lead profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichLeadResponse'
              example:
                data:
                  id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                  first_name: Jordan
                  last_name: Ellis
                  title: CEO
                  linkedin_url: https://www.linkedin.com/in/jordan-ellis
                  company:
                    id: 1035
                    name: Microsoft
                    domain: microsoft.com
                  work_history: []
                  education: []
                  skills: []
                meta:
                  amount_charged: 0.04
  /api/v1/enrich/database/company/:
    post:
      tags:
        - 6. Enrich
      summary: Enrich company from database
      description: Retrieve a company profile from cached data. Provide exactly one identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - title: By Generect ID
                  type: object
                  required:
                    - id
                  properties:
                    id:
                      type: string
                      description: Internal Generect company identifier returned by Search.
                      example: 1035
                - title: By LinkedIn URL
                  type: object
                  required:
                    - linkedin_url
                  properties:
                    linkedin_url:
                      type: string
                      description: >
                        LinkedIn company page URL. Supported formats:
                        linkedin.com/company/{slug}, linkedin.com/company/{id} (e.g. 12345),
                        linkedin.com/sales/company/{id}.
                      example: https://www.linkedin.com/company/microsoft/
                - title: By Domain
                  type: object
                  required:
                    - domain
                  properties:
                    domain:
                      type: string
                      description: Company website domain without protocol (e.g. microsoft.com).
                      example: microsoft.com
                - title: By Company Name
                  type: object
                  required:
                    - name
                  properties:
                    name:
                      type: string
                      description: Company name for fuzzy matching.
                      example: Microsoft
            examples:
              By Generect ID:
                value:
                  id: 1035
              By LinkedIn URL:
                value:
                  linkedin_url: https://www.linkedin.com/company/microsoft/
              By domain:
                value:
                  domain: microsoft.com
              By company name:
                value:
                  name: Microsoft
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"fields": "exactly one of id, domain, linkedin_url, name is required"}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '200':
          description: Full company profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichCompanyResponse'
              example:
                data:
                  id: 1035
                  name: Microsoft
                  domain: microsoft.com
                  linkedin_url: https://www.linkedin.com/company/microsoft/
                  industry: Software Development
                  headcount: 150
                meta:
                  amount_charged: 0.02
  /api/v1/enrich/realtime/company/:
    post:
      tags:
        - 6. Enrich
      summary: Enrich company in realtime
      description: Retrieve a fresh company profile. Provide exactly one identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - title: By Generect ID
                  type: object
                  required:
                    - id
                  properties:
                    id:
                      type: string
                      description: Internal Generect company identifier returned by Search.
                      example: 1035
                - title: By LinkedIn URL
                  type: object
                  required:
                    - linkedin_url
                  properties:
                    linkedin_url:
                      type: string
                      description: >
                        LinkedIn company page URL. Supported formats:
                        linkedin.com/company/{slug}, linkedin.com/company/{id} (e.g. 12345),
                        linkedin.com/sales/company/{id}.
                      example: https://www.linkedin.com/company/microsoft/
                - title: By Domain
                  type: object
                  required:
                    - domain
                  properties:
                    domain:
                      type: string
                      description: Company website domain without protocol (e.g. microsoft.com).
                      example: microsoft.com
                - title: By Company Name
                  type: object
                  required:
                    - name
                  properties:
                    name:
                      type: string
                      description: Company name for fuzzy matching.
                      example: Microsoft
            examples:
              By Generect ID:
                value:
                  id: 1035
              By LinkedIn URL:
                value:
                  linkedin_url: https://www.linkedin.com/company/microsoft/
              By domain:
                value:
                  domain: microsoft.com
              By company name:
                value:
                  name: Microsoft
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"fields": "exactly one of id, domain, linkedin_url, name is required"}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '200':
          description: Fresh full company profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichCompanyResponse'
              example:
                data:
                  id: 1035
                  name: Microsoft
                  domain: microsoft.com
                  linkedin_url: https://www.linkedin.com/company/microsoft/
                  industry: Software Development
                  headcount: 150
                meta:
                  amount_charged: 0.04
  /api/v1/enrich/database/leads/bulk/:
    post:
      tags:
        - 6. Enrich
      summary: Start bulk lead enrich (database)
      description: Start an asynchronous bulk lead enrich job from cached data. Billed per enriched lead; if a lead is not found, no credit is charged. Max 50 leads per request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadBulkEnrichRequest'
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"leads": ["This field is required."]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '202':
          description: Bulk job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSubmitResponse'
              example:
                data: null
                meta:
                  job_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                  status: pending
                  total: 2
                  processed: 0
                  amount_charged: 0
                  error: null
  /api/v1/enrich/realtime/leads/bulk/:
    post:
      tags:
        - 6. Enrich
      summary: Start bulk lead enrich (realtime)
      description: Start an asynchronous bulk lead enrich job with live data. Billed per enriched lead; if a lead is not found, no credit is charged. Max 50 leads per request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadBulkEnrichRequest'
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"leads": ["This field is required."]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '202':
          description: Bulk job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSubmitResponse'
              example:
                data: null
                meta:
                  job_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                  status: pending
                  total: 2
                  processed: 0
                  amount_charged: 0
                  error: null
  /api/v1/enrich/leads/bulk/{job_id}/:
    get:
      tags:
        - 6. Enrich
      summary: Get bulk lead enrich job
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
      responses:
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Job not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              example:
                detail: Job not found
        '200':
          description: Bulk job status and results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkStatusResponse'
              example:
                # Each item echoes its input verbatim (preserving order) and the
                # enriched lead, or lead: null when nothing was found. The lead
                # object is the same shape a database lead search returns
                # (languages/certifications/educations appear only on the
                # matching plan).
                data:
                  - input:
                      linkedin_url: https://www.linkedin.com/in/jordan-ellis
                    lead:
                      id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                      linkedin_id: '78461298'
                      first_name: Jordan
                      last_name: Ellis
                      full_name: Jordan Ellis
                      headline: CEO at Microsoft
                      job_title: Chief Executive Officer
                      company_name: Microsoft
                      company_industry: Software Development
                      linkedin_company_id: '1035'
                      linkedin_url: https://www.linkedin.com/in/jordan-ellis
                      location: San Francisco, California, United States
                      location_country: United States
                      gender: male
                      is_premium: true
                      jobs:
                        - company_name: Microsoft
                          job_title: Chief Executive Officer
                          job_started_on: '2014-02-01'
                          job_still_working: true
                      educations: []
                      languages: []
                      source: lead_by_link
                  - input:
                      id: ACwAAAFp2r4Bd1eF3gH5iJ7kL9mN0pQ2rS4tU6v
                    lead: null
                meta:
                  job_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                  status: completed
                  total: 2
                  processed: 2
                  found: 1
                  not_found: 1
                  amount_charged: 0.04
                  error: null
  /api/v1/enrich/database/companies/bulk/:
    post:
      tags:
        - 6. Enrich
      summary: Start bulk company enrich (database)
      description: Start an asynchronous bulk company enrich job from cached data. Billed per enriched company; if a company is not found, no credit is charged. Max 50 companies per request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyBulkEnrichRequest'
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"leads": ["This field is required."]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '202':
          description: Bulk job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSubmitResponse'
              example:
                data: null
                meta:
                  job_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                  status: pending
                  total: 2
                  processed: 0
                  amount_charged: 0
                  error: null
  /api/v1/enrich/realtime/companies/bulk/:
    post:
      tags:
        - 6. Enrich
      summary: Start bulk company enrich (realtime)
      description: Start an asynchronous bulk company enrich job with live data. Billed per enriched company; if a company is not found, no credit is charged. Max 50 companies per request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyBulkEnrichRequest'
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"leads": ["This field is required."]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '202':
          description: Bulk job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSubmitResponse'
              example:
                data: null
                meta:
                  job_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                  status: pending
                  total: 2
                  processed: 0
                  amount_charged: 0
                  error: null
  /api/v1/enrich/companies/bulk/{job_id}/:
    get:
      tags:
        - 6. Enrich
      summary: Get bulk company enrich job
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
      responses:
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Job not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              example:
                detail: Job not found
        '200':
          description: Bulk job status and results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkStatusResponse'
              example:
                # Each item echoes its input verbatim (preserving order) and the
                # enriched company, or company: null when nothing was found. The
                # company object is the same shape a database company search
                # returns (headcount_exact appears only on the matching plan).
                data:
                  - input:
                      domain: microsoft.com
                    company:
                      id: '1035'
                      name: Microsoft
                      domain: microsoft.com
                      website: https://www.microsoft.com
                      linkedin_id: '1035'
                      linkedin_link: https://www.linkedin.com/company/microsoft/
                      industry: Software Development
                      headcount_range: '10 000+'
                      headcount_exact: 228000
                      company_type: Public Company
                      founded_year: 1975
                      location: Redmond, Washington, United States
                      hq_country: United States
                      hq_city: Redmond
                  - input:
                      id: "999999999"
                    company: null
                meta:
                  job_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                  status: completed
                  total: 2
                  processed: 2
                  found: 1
                  not_found: 1
                  amount_charged: 0.04
                  error: null
  /api/v1/email/find/:
    post:
      tags:
        - 7. Email
      summary: Find email
      description: Find a verified work email by lead ID, LinkedIn URL, or by name and domain. Billed only when a valid email is found.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - title: By Lead ID
                  type: object
                  required:
                    - lead_id
                  properties:
                    lead_id:
                      type: string
                      description: Generect lead identifier from Search, Preview, or Enrich.
                      example: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                - title: By LinkedIn URL
                  type: object
                  required:
                    - linkedin_url
                  properties:
                    linkedin_url:
                      type: string
                      description: Lead's LinkedIn profile URL.
                      example: https://www.linkedin.com/in/jordan-ellis
                - title: By Name and Domain
                  type: object
                  required:
                    - first_name
                    - last_name
                    - domain
                  properties:
                    first_name:
                      type: string
                      description: Lead's first name.
                      example: John
                    last_name:
                      type: string
                      description: Lead's last name.
                      example: Doe
                    domain:
                      type: string
                      description: Company domain used to generate the email pattern.
                      example: microsoft.com
            examples:
              By Lead ID:
                value:
                  lead_id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
              By LinkedIn URL:
                value:
                  linkedin_url: https://www.linkedin.com/in/jordan-ellis
              By name and domain:
                value:
                  first_name: Jordan
                  last_name: Ellis
                  domain: microsoft.com
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"non_field_errors": ["Provide one of: lead_id, linkedin_url, or first_name+last_name+domain."]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '200':
          description: Email result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailFindResponse'
              examples:
                Found:
                  value:
                    data:
                      valid_email: jordan.ellis@microsoft.com
                      result: valid
                      catch_all: false
                      source: generect
                    meta:
                      amount_charged: 0.02
                Not found:
                  value:
                    data:
                      valid_email: null
                    meta:
                      amount_charged: 0
  /api/v1/email/find/bulk/:
    post:
      tags:
        - 7. Email
      summary: Start bulk email find
      description: Start an asynchronous bulk email find job. Billed only for valid emails found.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - leads
              properties:
                leads:
                  type: array
                  maxItems: 50
                  description: >-
                    Leads to find emails for (max 50 per request). Each entry is one of: {lead_id},
                    {linkedin_url}, or {first_name, last_name, domain}.
                  items:
                    oneOf:
                      - title: By Lead ID
                        type: object
                        required:
                          - lead_id
                        properties:
                          lead_id:
                            type: string
                            example: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                      - title: By LinkedIn URL
                        type: object
                        required:
                          - linkedin_url
                        properties:
                          linkedin_url:
                            type: string
                            example: https://www.linkedin.com/in/jordan-ellis
                      - title: By Name and Domain
                        type: object
                        required:
                          - first_name
                          - last_name
                          - domain
                        properties:
                          first_name:
                            type: string
                            description: Lead's first name.
                          last_name:
                            type: string
                            description: Lead's last name.
                          domain:
                            type: string
                            description: Company domain.
            examples:
              Bulk email find:
                value:
                  leads:
                    - lead_id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                    - first_name: Morgan
                      last_name: Lee
                      domain: salesforce.com
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"leads": ["This field is required."]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '202':
          description: Bulk job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSubmitResponse'
              example:
                data: null
                meta:
                  job_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                  status: pending
                  total: 2
                  processed: 0
                  amount_charged: 0
                  error: null
  /api/v1/email/find/bulk/{job_id}/:
    get:
      tags:
        - 7. Email
      summary: Get bulk email find job
      description: Retrieve the status and results of a bulk email find job.
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
      responses:
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Job not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              example:
                detail: Job not found
        '200':
          description: Bulk job status and results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkStatusResponse'
              example:
                data:
                  - lead_id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                    valid_email: jordan.ellis@microsoft.com
                    result: valid
                    catch_all: false
                    source: generect
                  - valid_email: null
                meta:
                  job_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                  status: completed
                  total: 2
                  processed: 2
                  amount_charged: 0.02
                  error: null
  /api/v1/email/validate/:
    post:
      tags:
        - 7. Email
      summary: Validate emails
      description: Validate email deliverability and risk. Billed per email validated.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - emails
              properties:
                emails:
                  type: array
                  items:
                    type: string
              example:
                emails:
                  - jordan.ellis@microsoft.com
                  - morgan.lee@salesforce.com
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"emails": ["This field is required."]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '200':
          description: Validation results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailValidateResponse'
              example:
                data:
                  - email: jordan.ellis@microsoft.com
                    result: valid
                    exist: "yes"
                    catch_all: false
                    error: null
                  - email: morgan.lee@salesforce.com
                    result: valid
                    exist: "yes"
                    catch_all: false
                    error: null
                meta:
                  amount_charged: 0.01
  /api/v1/accounts/me/:
    get:
      tags:
        - 8. Accounts
      summary: Get account profile
      description: Retrieve the current account profile, credit balance, monthly usage, and Preview tier eligibility.
      responses:
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '200':
          description: Account profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountMeResponse'
              example:
                data:
                  id: a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7
                  email: jordan.ellis@microsoft.com
                  name: Jordan Ellis
                  plan: Pro
                  credits:
                    balance: 5000
                    used_this_month: 1234
                    monthly_limit: 10000
                  preview_tier: true
  /api/v1/accounts/usage/:
    get:
      tags:
        - 8. Accounts
      summary: Get account usage
      description: Retrieve credit usage statistics and operation breakdown for an account.
      parameters:
        - name: timezone
          in: query
          required: false
          description: IANA timezone for aggregation.
          schema:
            type: string
            default: UTC
          example: Europe/Kyiv
        - name: period
          in: query
          required: false
          description: Truncation granularity for the usage series.
          schema:
            type: string
            enum: [day, week, month]
            default: day
        - name: start_date
          in: query
          required: false
          schema:
            type: string
          example: '2026-05-01'
        - name: end_date
          in: query
          required: false
          schema:
            type: string
          example: '2026-05-31'
        - name: period_month
          in: query
          required: false
          description: Month label for the response (YYYY-MM).
          schema:
            type: string
          example: '2026-05'
      responses:
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '200':
          description: Account usage statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountUsageResponse'
              example:
                data:
                  period: '2026-05'
                  total_credits: 1234
                  breakdown:
                    search_database: 500
                    search_realtime: 200
                    enrich_database: 300
                    enrich_realtime: 100
                    email_find: 134
  /api/v1/accounts/transactions/:
    get:
      tags:
        - 8. Accounts
      summary: Get account transactions
      description: Retrieve account credit transaction history.
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
      responses:
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '200':
          description: Account transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountTransactionsResponse'
              example:
                data:
                  transactions:
                    - id: f0e1d2c3-b4a5-4697-8c9d-0e1f2a3b4c5d
                      timestamp: '2026-05-15T10:30:00Z'
                      type: search_database_leads
                      credits: -25
                      details:
                        balance_type: leads_by_icp
                        status: success
  /api/v1/search/database/leads/:
    post:
      tags:
        - 9. Search
      summary: Search database leads
      description: Search cached leads. Database mode returns results in under 1 second. Billed per result returned.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadSearchRequest'
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"company_headcounts": ["Object with name=999 does not exist."]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '200':
          description: Full lead search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchLeadsResponse'
              example:
                data:
                  leads:
                    - lead_id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                      first_name: Jordan
                      last_name: Ellis
                      title: CEO
                  results_count: 1240
                meta:
                  amount_charged: 24.8
  /api/v1/search/database/leads/count/:
    post:
      tags:
        - 9. Search
      summary: Count database leads
      description: Count cached leads matching filters. Always free.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadSearchRequest'
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"company_headcounts": ["Object with name=999 does not exist."]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '200':
          description: Matching lead count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchCountResponse'
              example:
                data:
                  results_count: 1240
                meta:
                  amount_charged: 0
  /api/v1/search/database/companies/:
    post:
      tags:
        - 9. Search
      summary: Search database companies
      description: Search cached companies. Database mode returns results in under 1 second. Billed per result returned.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanySearchRequest'
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"headcounts": ["Object with name=999 does not exist."]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '200':
          description: Full company search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchCompaniesResponse'
              example:
                data:
                  companies:
                    - linkedin_id: '1035'
                      name: Microsoft
                      domain: microsoft.com
                  results_count: 530
                meta:
                  amount_charged: 10.6
  /api/v1/search/database/companies/count/:
    post:
      tags:
        - 9. Search
      summary: Count database companies
      description: Count cached companies matching filters. Always free.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanySearchRequest'
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"headcounts": ["Object with name=999 does not exist."]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '200':
          description: Matching company count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchCountResponse'
              example:
                data:
                  results_count: 530
                meta:
                  amount_charged: 0
  /api/v1/search/database/company-leads/:
    post:
      tags:
        - 9. Search
      summary: Search database company leads
      description: Search cached leads at matching companies.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyLeadSearchRequest'
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"non_field_errors": ["company_search_criteria or lead_search_criteria must be specified"]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '200':
          description: Full company-lead search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchCompanyLeadsResponse'
              example:
                data:
                  leads:
                    - lead_id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                      first_name: Jordan
                      last_name: Ellis
                  results_count: 320
                meta:
                  amount_charged: 6.4
  /api/v1/search/database/company-leads/count/:
    post:
      tags:
        - 9. Search
      summary: Count database company leads
      description: Count cached company-lead matches. Database count endpoints are free.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyLeadSearchRequest'
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"non_field_errors": ["company_search_criteria or lead_search_criteria must be specified"]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '200':
          description: Matching company-lead count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyLeadsCountResponse'
              example:
                data:
                  results_count: 320
                  companies_count: 45
                  leads_count: 320
                meta:
                  amount_charged: 0
  /api/v1/search/realtime/leads/:
    post:
      tags:
        - 9. Search
      summary: Search realtime leads
      description: Search fresh leads with advanced filters (keywords, past companies, schools, groups). Response time 5-60 sec. Billed per result returned.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RealtimeLeadSearchRequest'
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"company_headcounts": ["Object with name=999 does not exist."]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '200':
          description: Full realtime lead search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchLeadsResponse'
              example:
                data:
                  leads:
                    - lead_id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                      first_name: Jordan
                      last_name: Ellis
                      title: CEO
                  results_count: 1240
                meta:
                  amount_charged: 49.6
  /api/v1/search/realtime/leads/count/:
    post:
      tags:
        - 9. Search
      summary: Count realtime leads
      description: Count fresh leads matching filters. Billed per request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RealtimeLeadSearchRequest'
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"company_headcounts": ["Object with name=999 does not exist."]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '200':
          description: Matching realtime lead count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchCountResponse'
              example:
                data:
                  results_count: 1240
                meta:
                  amount_charged: 0.04
  /api/v1/search/realtime/companies/:
    post:
      tags:
        - 9. Search
      summary: Search realtime companies
      description: Search fresh companies with advanced filters (revenue, department headcount, growth). Response time 5-60 sec. Billed per result returned.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RealtimeCompanySearchRequest'
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"headcounts": ["Object with name=999 does not exist."]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '200':
          description: Full realtime company search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchCompaniesResponse'
              example:
                data:
                  companies:
                    - linkedin_id: '1035'
                      name: Microsoft
                      domain: microsoft.com
                  results_count: 530
                meta:
                  amount_charged: 21.2
  /api/v1/search/realtime/companies/count/:
    post:
      tags:
        - 9. Search
      summary: Count realtime companies
      description: Count fresh companies matching filters. Billed per request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RealtimeCompanySearchRequest'
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"headcounts": ["Object with name=999 does not exist."]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '200':
          description: Matching realtime company count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchCountResponse'
              example:
                data:
                  results_count: 530
                meta:
                  amount_charged: 0.04
  /api/v1/search/realtime/company-leads/:
    post:
      tags:
        - 9. Search
      summary: Search realtime company leads
      description: Search fresh leads at matching companies.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RealtimeCompanyLeadSearchRequest'
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"non_field_errors": ["company_search_criteria or lead_search_criteria must be specified"]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '200':
          description: Full realtime company-lead search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchCompanyLeadsResponse'
              example:
                data:
                  leads:
                    - lead_id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                      first_name: Jordan
                      last_name: Ellis
                  results_count: 320
                meta:
                  amount_charged: 12.8
  /api/v1/phone/find/:
    post:
      tags:
        - 10. Phone
      summary: Find phone
      description: Find a phone number by lead ID, LinkedIn URL, or by name and company. Billed only when a phone number is found.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - title: By Lead ID
                  type: object
                  required:
                    - lead_id
                  properties:
                    lead_id:
                      type: string
                      description: Generect lead identifier from Search, Preview, or Enrich.
                      example: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                - title: By LinkedIn URL
                  type: object
                  required:
                    - linkedin_url
                  properties:
                    linkedin_url:
                      type: string
                      description: LinkedIn profile URL.
                      example: https://www.linkedin.com/in/jordan-ellis
                - $ref: '#/components/schemas/PhoneFindByNameRequest'
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"non_field_errors": ["Provide one of: lead_id, linkedin_url, or first_name+last_name+company."]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '200':
          description: Phone finder result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneFindResponse'
              examples:
                Found:
                  value:
                    data:
                      lead_id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                      phone:
                        number: '+14155550123'
                        status: FOUND
                        type: mobile
                        country: US
                    meta:
                      amount_charged: 0.4
                Not found:
                  value:
                    data:
                      lead_id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                      phone:
                        number: null
                        status: NOT_FOUND
                    meta:
                      amount_charged: 0
  /api/v1/phone/find/bulk/:
    post:
      tags:
        - 10. Phone
      summary: Start bulk phone find
      description: Start an asynchronous bulk phone finder job. Billed only for phone numbers found.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - leads
              properties:
                leads:
                  type: array
                  maxItems: 50
                  description: List of leads to find phones for (max 50 per request). Each entry is either a lead_id, linkedin_url, or name+company.
                  items:
                    oneOf:
                      - title: By Lead ID
                        type: object
                        required:
                          - lead_id
                        properties:
                          lead_id:
                            type: string
                            description: Generect lead identifier.
                      - title: By LinkedIn URL
                        type: object
                        required:
                          - linkedin_url
                        properties:
                          linkedin_url:
                            type: string
                            example: https://www.linkedin.com/in/jordan-ellis
                      - $ref: '#/components/schemas/PhoneFindByNameRequest'
            examples:
              Bulk phone find:
                value:
                  leads:
                    - lead_id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                    - first_name: Jordan
                      last_name: Ellis
                      company: microsoft.com
      responses:
        '400':
          description: Validation error or insufficient balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"leads": ["This field is required."]}
                Insufficient funds:
                  value:
                    status: error
                    status_code: 400
                    detail: Insufficient funds in the account.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '202':
          description: Bulk phone job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSubmitResponse'
              example:
                data: null
                meta:
                  job_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                  status: pending
                  total: 2
                  processed: 0
                  amount_charged: 0
                  error: null
  /api/v1/phone/find/bulk/{job_id}/:
    get:
      tags:
        - 10. Phone
      summary: Get bulk phone find job
      description: Retrieve the status and results of a bulk phone finder job.
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
      responses:
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Job not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              example:
                detail: Job not found
        '200':
          description: Bulk phone job status and results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkStatusResponse'
              example:
                data:
                  - lead_id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                    phone:
                      number: '+14155550123'
                      status: FOUND
                      type: mobile
                      country: US
                  - lead_id: ACwAAAFp2r4Bd1eF3gH5iJ7kL9mN0pQ2rS4tU6v
                    phone:
                      number: null
                      status: NOT_FOUND
                meta:
                  job_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                  status: completed
                  total: 2
                  processed: 2
                  amount_charged: 0.4
                  error: null
  /api/v1/webhooks/:
    get:
      tags:
        - 11. Webhooks
      summary: List webhooks
      description: List registered webhook endpoints.
      responses:
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '200':
          description: Registered webhooks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'
    post:
      tags:
        - 11. Webhooks
      summary: Register webhook
      description: Register a webhook endpoint for async notifications.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
                - events
              properties:
                url:
                  type: string
                  description: Your HTTPS endpoint URL to receive webhook events.
                  example: https://your-app.com/webhook
                events:
                  type: array
                  description: Events to subscribe to.
                  items:
                    type: string
                    enum:
                      - email.find.bulk.completed
                      - phone.find.bulk.completed
                      - enrich.lead.bulk.completed
                      - enrich.company.bulk.completed
                  example:
                    - email.find.bulk.completed
                secret:
                  type: string
                  description: Secret for HMAC signature verification of incoming webhook payloads.
                  example: your-secret-for-signature
      responses:
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"events": ["Unsupported events: ['email.find.completed']. Allowed: ['email.find.bulk.completed', 'enrich.company.bulk.completed', 'enrich.lead.bulk.completed', 'phone.find.bulk.completed']"]}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '201':
          description: Webhook registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
  /api/v1/webhooks/{id}/:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        example: wh_123
    get:
      tags:
        - 11. Webhooks
      summary: Retrieve webhook
      description: Retrieve a single registered webhook endpoint.
      responses:
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '200':
          description: Webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
    put:
      tags:
        - 11. Webhooks
      summary: Update webhook
      description: Replace a webhook endpoint's configuration.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
                - events
              properties:
                url:
                  type: string
                  example: https://your-app.com/webhook
                events:
                  type: array
                  items:
                    type: string
                    enum:
                      - email.find.bulk.completed
                      - phone.find.bulk.completed
                      - enrich.lead.bulk.completed
                      - enrich.company.bulk.completed
                secret:
                  type: string
      responses:
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"events": ["Unsupported events: ['email.find.completed']. Allowed: ['email.find.bulk.completed', 'enrich.company.bulk.completed', 'enrich.lead.bulk.completed', 'phone.find.bulk.completed']"]}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '200':
          description: Webhook updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
    patch:
      tags:
        - 11. Webhooks
      summary: Partially update webhook
      description: Update selected fields of a webhook endpoint.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                events:
                  type: array
                  items:
                    type: string
                    enum:
                      - email.find.bulk.completed
                      - phone.find.bulk.completed
                      - enrich.lead.bulk.completed
                      - enrich.company.bulk.completed
                secret:
                  type: string
      responses:
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail: {"events": ["Unsupported events: ['email.find.completed']. Allowed: ['email.find.bulk.completed', 'enrich.company.bulk.completed', 'enrich.lead.bulk.completed', 'phone.find.bulk.completed']"]}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '200':
          description: Webhook updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
    delete:
      tags:
        - 11. Webhooks
      summary: Delete webhook
      description: Remove a registered webhook endpoint.
      responses:
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '204':
          description: Webhook removed
  /api/v1/webhooks/{id}/test/:
    post:
      tags:
        - 11. Webhooks
      summary: Test webhook
      description: Send a sample `webhook.test` delivery to this webhook's URL.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: wh_123
      responses:
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '202':
          description: Test delivery enqueued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookTestResponse'
              example:
                data:
                  delivery_id: d4e5f6a7-8b9c-40d1-a2e3-f4a5b6c7d8e9
                  status: pending
                meta:
                  event: webhook.test
components:
  schemas:
    LeadBulkEnrichRequest:
      type: object
      required:
        - leads
      properties:
        leads:
          type: array
          maxItems: 50
          description: >-
            Leads to enrich (max 50 per request). Each entry provides exactly
            one identifier: id, linkedin_url, or email.
          items:
            oneOf:
              - title: By Lead ID
                type: object
                required:
                  - id
                properties:
                  id:
                    type: string
                    example: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
              - title: By LinkedIn URL
                type: object
                required:
                  - linkedin_url
                properties:
                  linkedin_url:
                    type: string
                    example: https://www.linkedin.com/in/jordan-ellis
              - title: By Email
                type: object
                required:
                  - email
                properties:
                  email:
                    type: string
                    example: jordan.ellis@microsoft.com
      example:
        leads:
          - linkedin_url: https://www.linkedin.com/in/jordan-ellis
          - id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
    CompanyBulkEnrichRequest:
      type: object
      required:
        - companies
      properties:
        companies:
          type: array
          maxItems: 50
          description: >-
            Companies to enrich (max 50 per request). Each entry provides
            exactly one identifier: id, domain, linkedin_url, or name.
          items:
            oneOf:
              - title: By LinkedIn URL
                type: object
                required:
                  - linkedin_url
                properties:
                  linkedin_url:
                    type: string
                    example: https://www.linkedin.com/company/microsoft/
              - title: By Domain
                type: object
                required:
                  - domain
                properties:
                  domain:
                    type: string
                    example: microsoft.com
              - title: By Company ID
                type: object
                required:
                  - id
                properties:
                  id:
                    type: string
                    example: "1035"
              - title: By Name
                type: object
                required:
                  - name
                properties:
                  name:
                    type: string
                    example: Microsoft
      example:
        companies:
          - domain: microsoft.com
          - linkedin_url: https://www.linkedin.com/company/microsoft/
    Error:
      type: object
      description: Standard error envelope returned for 4xx/5xx responses.
      properties:
        status:
          type: string
          example: error
        status_code:
          type: integer
          example: 400
        detail:
          description: >-
            Human-readable message (string) for most errors, or a field-level
            validation map ({ field: [messages] }) for 400 validation errors.
          example: Insufficient funds in the account.
    LeadSearchRequest:
      type: object
      properties:
        job_titles:
          type: array
          items:
            type: string
          description: >-
            Job titles held by the people you want to find. A lead only needs to match one of the titles you provide — adding more expands your search. Results may also include similar titles (e.g. "marketing manager" can return "content marketing manager"). Combine with seniorities to target both function and level. Examples: "sales development representative", "marketing manager", "software engineer".
        seniorities:
          type: array
          items:
            type: string
          description: >-
            Job seniority levels at the lead's current employer (current position only, not previous roles). A lead needs to match at least one; adding more values expands your search. Allowed values: owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern. Combine with job_titles to narrow targeting.
        locations:
          type: array
          items:
            type: string
          description: >-
            Geographic locations where leads currently live — matches across cities, states/regions and countries. A lead needs to match at least one. To filter by the employer's HQ location, use company_locations. Examples: "San Francisco, California, United States", "Germany", "London".
        exclude_locations:
          type: array
          items:
            type: string
          description: Locations to exclude from results.
        company_locations:
          type: array
          items:
            type: string
          description: >-
            Headquarters location of the lead's current employer; a lead is included if their company's HQ matches at least one. Filters by where the company is based — distinct from locations, which is where the lead personally lives.
        exclude_company_locations:
          type: array
          items:
            type: string
          description: Company locations to exclude.
        company_industries:
          type: array
          items:
            type: string
          description: >-
            Industries of the lead's current employer; a lead is included if their company matches at least one. Values follow LinkedIn's industry taxonomy. Examples: "Software Development", "Financial Services", "Information Technology".
        exclude_company_industries:
          type: array
          items:
            type: string
          description: Company industries to exclude.
        company_headcounts:
          type: array
          items:
            type: string
          description: >-
            Size of the lead's current employer, as employee-count ranges; a lead is included if their company falls into at least one. Allowed values: "1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10 000+".
        exclude_company_headcounts:
          type: array
          items:
            type: string
          description: Company size ranges to exclude.
        company_types:
          type: array
          items:
            type: string
          description: 'Company types: "Public Company", "Privately Held", "Non Profit", "Government Agency", "Educational", "Self Employed", "Partnership", "Self Owned".'
        company_name:
          type: string
          description: Target company name (mutually exclusive with company_link and company_id).
        company_link:
          type: string
          description: LinkedIn company URL (mutually exclusive with company_name and company_id).
        company_id:
          type: integer
          description: LinkedIn company numeric ID (mutually exclusive with company_name and company_link).
        personas:
          type: array
          description: 'List of persona tuples. Each persona: [name, functions, seniorities, prohibits, priority?].'
          items:
            type: array
        exclude_names:
          type: array
          items:
            type: string
          description: Skip leads by full name.
        exclude_ids:
          type: array
          items:
            type: string
          description: Skip leads by Sales Navigator ID.
        filter_empty_vars:
          type: array
          items:
            type: string
          description: 'Skip leads where these fields are empty. Options: job_started_on, profile_photo, started_at_position, company_website.'
        limit_by:
          type: integer
          description: >-
            Maximum number of leads to return. For filter-only searches
            (no company_id/company_link/company_name) the maximum is 2400.
        offset_by:
          type: integer
          description: >-
            Number of leads to skip (for pagination). For filter-only
            searches the maximum is 2399.
        strict:
          type: array
          items:
            type: string
          description: Fields to apply strict matching on (e.g. "company_locations").
      example:
        job_titles:
          - CEO
          - Founder
        seniorities:
          - c_suite
        locations:
          - United States
        company_industries:
          - Software Development
        company_headcounts:
          - 51-200
        limit_by: 50
    RealtimeLeadSearchRequest:
      allOf:
        - $ref: '#/components/schemas/LeadSearchRequest'
        - type: object
          properties:
            keywords:
              type: array
              items:
                type: string
              description: >-
                Free-text keywords searched across lead profiles (headline, current job description, skills, summary); a lead is included if their profile contains at least one. Realtime mode only — database mode does not support free-text search. Examples: "machine learning", "growth marketing", "kubernetes".
            functions:
              type: array
              items:
                type: string
              description: >-
                Job functions — categorize roles by business area, independent of seniority or title; a lead is included if their function matches at least one. Common values: Sales, Marketing, Engineering, Operations, Finance, HR, Product, Customer Success, Legal, Data. Combine with seniorities for function-by-seniority targeting.
            past_company_names:
              type: array
              items:
                type: string
              description: >-
                Filter by companies where the lead previously worked; a lead is included if their work history contains at least one. Useful for alumni outreach (e.g. ex-Google engineers) or targeting people who left a competitor. Examples: "Google", "Meta", "Stripe".
            schools:
              type: array
              items:
                type: integer
              description: School IDs to filter by.
            groups:
              type: array
              items:
                type: integer
              description: LinkedIn group IDs to filter by.
            years_in_position:
              type: array
              items:
                type: integer
              description: 'Time in current position: 1 = under 1y, 2 = 1-2y, 3 = 3-5y, 4 = 6-10y, 5 = 10y+.'
            years_in_company:
              type: array
              items:
                type: integer
              description: 'Time at current company: 1 = under 1y, 2 = 1-2y, 3 = 3-5y, 4 = 6-10y, 5 = 10y+.'
            changed_jobs:
              type: boolean
              description: Filter for leads who recently changed jobs.
              default: false
            posted_on_linkedin:
              type: boolean
              description: Filter for leads who recently posted on LinkedIn.
              default: false
            linkedin_filter_link:
              type: string
              description: Pre-built LinkedIn or Sales Navigator search URL to extract filters from.
    CompanySearchRequest:
      type: object
      properties:
        industries:
          type: array
          items:
            type: string
          description: >-
            Industries of the target companies; a company is included if it matches at least one. Values follow LinkedIn's industry taxonomy. Examples: "Software Development", "Financial Services", "Information Technology".
        exclude_industries:
          type: array
          items:
            type: string
          description: Industries to exclude.
        sub_industries:
          type: boolean
          default: false
          description: >-
            Controls how the `industries` filter maps onto LinkedIn's industry
            taxonomy. By default (`false`), a selected industry also matches
            companies in its sub-industries. Set to `true` to match only the
            industries you specify and exclude their sub-industries, for finer
            sub-category targeting — for example, "Manufacturing" without
            "Chemicals".
        headcounts:
          type: array
          items:
            type: string
          description: >-
            Company size, as employee-count ranges; a company is included if it falls into at least one. Allowed values: "1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10 000+".
        locations:
          type: array
          items:
            type: string
          description: >-
            Company headquarters locations — matches across cities, states/regions and countries; a company is included if its HQ matches at least one. Examples: "United States", "San Francisco, California, United States", "Germany".
        exclude_locations:
          type: array
          items:
            type: string
          description: Locations to exclude.
        company_types:
          type: array
          items:
            type: string
          description: 'Company types: "Public Company", "Privately Held", "Non Profit", "Government Agency", "Educational", etc.'
        num_of_followers:
          type: array
          items:
            type: string
          description: 'Follower count ranges: "1-50", "51-100", "101-1000", "1001-5000", "5001+".'
        keywords:
          type: array
          items:
            type: string
          description: >-
            Free-text keywords matched across company profiles (name, description, specialties); a company is included if it contains at least one. OR logic, max 10 keywords, up to 40 characters each. Examples: "platform", "marketplace", "developer tools".
        technologies:
          type: array
          items:
            type: string
          description: Technologies used by the company.
        company_names:
          type: array
          items:
            type: string
          description: Search by specific company names.
        exclude_ids:
          type: array
          items:
            type: string
          description: Exclude companies by LinkedIn ID or URN.
        exclude_domains:
          type: array
          items:
            type: string
          description: Exclude companies by domain.
        limit_by:
          type: integer
          description: Maximum number of companies to return (1-1600).
        offset_by:
          type: integer
          description: Number of companies to skip (0-1599, for pagination).
        strict:
          type: array
          items:
            type: string
          description: Fields to apply strict matching on (e.g. "company_locations").
      example:
        industries:
          - Software Development
        headcounts:
          - 51-200
        locations:
          - United States
        limit_by: 50
    RealtimeCompanySearchRequest:
      allOf:
        - $ref: '#/components/schemas/CompanySearchRequest'
        - type: object
          properties:
            revenues_range:
              type: object
              description: 'Revenue filter with min/max (e.g. {"min": 1000000, "max": 50000000}).'
              properties:
                min:
                  type: number
                max:
                  type: number
            department_headcount:
              type: object
              description: 'Filter by department size (e.g. {"name": "engineering", "min": 10, "max": 100}).'
              properties:
                name:
                  type: string
                min:
                  type: number
                max:
                  type: number
            headcount_growth:
              type: object
              description: 'Filter by headcount growth percentage (e.g. {"min": 5, "max": 50}).'
              properties:
                min:
                  type: number
                max:
                  type: number
            hiring_on_linkedin:
              type: boolean
              description: Filter for companies actively hiring on LinkedIn.
              default: false
            linkedins_links:
              type: array
              items:
                type: string
              description: Filter by specific LinkedIn company URLs.
    CompanyLeadSearchRequest:
      type: object
      properties:
        company_search_criteria:
          $ref: '#/components/schemas/CompanySearchRequest'
        lead_search_criteria:
          $ref: '#/components/schemas/LeadSearchRequest'
      example:
        company_search_criteria:
          industries:
            - Software Development
          headcounts:
            - 51-200
          locations:
            - United States
        lead_search_criteria:
          job_titles:
            - CEO
          seniorities:
            - c_suite
          locations:
            - United States
    RealtimeCompanyLeadSearchRequest:
      type: object
      properties:
        company_search_criteria:
          $ref: '#/components/schemas/RealtimeCompanySearchRequest'
        lead_search_criteria:
          $ref: '#/components/schemas/RealtimeLeadSearchRequest'
      example:
        company_search_criteria:
          industries:
            - Software Development
          headcounts:
            - 51-200
          locations:
            - United States
        lead_search_criteria:
          job_titles:
            - CEO
          seniorities:
            - c_suite
          locations:
            - United States
    PhoneFindByNameRequest:
      title: By Name and Company
      type: object
      required:
        - first_name
        - last_name
        - company
      properties:
        first_name:
          type: string
          description: Lead's first name.
          example: John
        last_name:
          type: string
          description: Lead's last name.
          example: Doe
        company:
          type: string
          description: Company name or domain where the lead works.
          example: microsoft.com
        linkedin_url:
          type: string
          description: Optional LinkedIn profile URL to improve match accuracy.
          example: https://www.linkedin.com/in/jordan-ellis
    Meta:
      type: object
      description: Operation metadata returned in every data/meta response.
      required:
        - amount_charged
      properties:
        amount_charged:
          type: number
          description: >-
            Actual amount charged for this request in USD, computed from your
            pricing tier. 0 for free operations and for not-found results
            (No Data — No Charge).
        status:
          type: string
          description: Set to "error" when the operation finished with an error.
        error:
          type: string
          description: Error details; present only when the operation failed.
        time_cached:
          type: string
          format: date-time
          description: >-
            When the cached result set was originally collected (returned by
            database company search when results are served from a previous
            identical search).
    BulkJobMeta:
      type: object
      description: >-
        Bulk job state. Poll the bulk status endpoint with job_id or subscribe
        to the completion webhook.
      required:
        - job_id
        - status
        - total
        - processed
        - amount_charged
      properties:
        job_id:
          type: string
          description: Job identifier — pass it to the bulk status endpoint.
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - error
        total:
          type: integer
          description: Number of submitted items.
        processed:
          type: integer
          description: Items processed so far.
        found:
          type: integer
          description: Items that resolved to a result (present on status/webhook once completed).
        not_found:
          type: integer
          description: Items with no result — not charged (No Data, No Charge).
        amount_charged:
          type: number
          description: USD charged for found results; final when status is completed.
        error:
          type: string
          nullable: true
          description: Failure reason when status is error.
    SearchLeadsResponse:
      type: object
      properties:
        data:
          type: object
          description: Search results.
          properties:
            leads:
              type: array
              description: Lead profiles — see the example for the full field set.
              items:
                type: object
            results_count:
              type: integer
              description: Total number of leads matching the query.
        meta:
          $ref: '#/components/schemas/Meta'
    SearchCompaniesResponse:
      type: object
      properties:
        data:
          type: object
          description: Search results.
          properties:
            companies:
              type: array
              description: Company profiles — see the example for the full field set.
              items:
                type: object
            results_count:
              type: integer
              description: Total number of companies matching the query.
        meta:
          $ref: '#/components/schemas/Meta'
    SearchCompanyLeadsResponse:
      type: object
      properties:
        data:
          type: object
          description: >-
            Search results. Either leads or companies is populated depending on
            whether lead_search_criteria was provided.
          properties:
            companies:
              type: array
              items:
                type: object
            leads:
              type: array
              items:
                type: object
            companies_count:
              type: integer
            leads_count:
              type: integer
            results_count:
              type: integer
        meta:
          $ref: '#/components/schemas/Meta'
    SearchCountResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            results_count:
              type: integer
              description: Number of records matching the filters.
        meta:
          $ref: '#/components/schemas/Meta'
    CompanyLeadsCountResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            results_count:
              type: integer
            companies_count:
              type: integer
            leads_count:
              type: integer
        meta:
          $ref: '#/components/schemas/Meta'
    PreviewLeadsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            leads:
              type: array
              description: Masked lead previews — see the example for the field set.
              items:
                type: object
        meta:
          $ref: '#/components/schemas/Meta'
    PreviewCountResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            count:
              type: integer
              description: Number of preview leads matching the filters.
        meta:
          $ref: '#/components/schemas/Meta'
    EnrichLeadResponse:
      type: object
      properties:
        data:
          type: object
          description: Full lead profile — see the example for the field set.
        meta:
          $ref: '#/components/schemas/Meta'
    EnrichCompanyResponse:
      type: object
      properties:
        data:
          type: object
          description: Full company profile — see the example for the field set.
        meta:
          $ref: '#/components/schemas/Meta'
    EmailFindResponse:
      type: object
      properties:
        data:
          type: object
          description: The email finder result. valid_email is null when no email is found.
          properties:
            lead_id:
              type: string
              description: Echoed back when the request was made by lead_id.
            valid_email:
              type: string
              nullable: true
              description: The found verified email, or null if none was found.
            result:
              type: string
              description: 'Outcome: valid, invalid, or unknown.'
            catch_all:
              type: boolean
              description: True if the domain is catch-all.
            source:
              type: string
              description: Where the email was resolved (e.g. generect, findymail, FORMAT).
            email_format:
              type: string
              description: Detected address pattern for the domain.
            mx_domain:
              type: string
              description: Mail exchanger domain.
        meta:
          $ref: '#/components/schemas/Meta'
    EmailValidateResponse:
      type: object
      properties:
        data:
          type: array
          description: One validation result per submitted email, in input order.
          items:
            type: object
            properties:
              email:
                type: string
                description: The validated email address.
              result:
                type: string
                description: 'Validation outcome: valid, invalid, catch_all, or unknown.'
              exist:
                type: string
                description: Whether the mailbox exists (e.g. "yes", "no").
              catch_all:
                type: boolean
                description: True if the domain accepts mail for any address (catch-all).
              error:
                type: string
                nullable: true
                description: Reason the address could not be validated; null on success.
        meta:
          $ref: '#/components/schemas/Meta'
    PhoneFindResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            lead_id:
              type: string
              nullable: true
              description: Resolved lead identifier, when the input matched a lead.
            phone:
              type: object
              properties:
                number:
                  type: string
                  nullable: true
                  description: Phone number in E.164 format; null when not found.
                status:
                  type: string
                  enum:
                    - FOUND
                    - NOT_FOUND
                type:
                  type: string
                  description: Number type (mobile, fixed_line, voip, ...). Present when found.
                country:
                  type: string
                  description: ISO country code. Present when found.
        meta:
          $ref: '#/components/schemas/Meta'
    BulkSubmitResponse:
      type: object
      properties:
        data:
          type: object
          nullable: true
          description: Always null — results arrive via the bulk status endpoint.
        meta:
          $ref: '#/components/schemas/BulkJobMeta'
    BulkStatusResponse:
      type: object
      properties:
        data:
          type: array
          nullable: true
          description: Result items once status is completed; null until then.
          items:
            type: object
        meta:
          $ref: '#/components/schemas/BulkJobMeta'
    Webhook:
      type: object
      properties:
        id:
          type: string
          description: Webhook identifier.
        url:
          type: string
          description: Your HTTPS endpoint that receives events.
        events:
          type: array
          items:
            type: string
          description: Subscribed event types.
        secret:
          type: string
          description: Secret used for HMAC signature verification.
        is_active:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    WebhookList:
      type: array
      description: Registered webhooks.
      items:
        $ref: '#/components/schemas/Webhook'
    WebhookTestResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            delivery_id:
              type: string
              description: Identifier of the test delivery.
            status:
              type: string
              description: Delivery status (pending until your endpoint responds).
        meta:
          type: object
          properties:
            event:
              type: string
              description: Always "webhook.test".

    AccountMeResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
            email:
              type: string
            name:
              type: string
            plan:
              type: string
            credits:
              type: object
              description: Credit balance summary.
              properties:
                balance:
                  type: number
                  description: Current credit balance.
                used_this_month:
                  type: number
                monthly_limit:
                  type: number
            preview_tier:
              type: boolean
              description: Whether the account is eligible for the Preview endpoints.
    AccountUsageResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            period:
              type: string
              description: Reporting period the stats cover.
            total_credits:
              type: number
              description: Total credits consumed in the period.
            breakdown:
              type: object
              description: Credits consumed per operation type.
              additionalProperties:
                type: number
    AccountTransactionsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            transactions:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  type:
                    type: string
                    description: Operation that produced the transaction.
                  credits:
                    type: number
                    description: Credit delta (negative for charges).
                  details:
                    type: object
                    properties:
                      balance_type:
                        type: string
                      status:
                        type: string

  responses:
    Unauthorized:
      description: Missing or invalid API token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            status_code: 401
            detail: Authentication credentials were not provided.
    Forbidden:
      description: Authenticated, but the account/plan is not allowed to use this endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            status_code: 403
            detail: You do not have permission to perform this action.
    NotFound:
      description: Resource or job not found (or not owned by the caller).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            status_code: 404
            detail: Not found.
    TooManyRequests:
      description: Rate limit exceeded — retry later.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            status_code: 429
            detail: Request was throttled.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: "Use the required Token prefix. Example: Authorization: Token xxxxxxxxx"
security:
  - apiKey: []
tags:
  - name: 1. Auth
    description: Login and get user info
  - name: 2. Transactions
    description: List of latest transactions in your account
  - name: 3. Leads
    description: Fetch information about leads by _link/name/ICP_.
  - name: 4. Companies
    description: Fetch information about companies by link/name/ICP.
  - name: 5. Preview
    description: Search masked database leads for preview and reveal workflows.
  - name: 6. Enrich
    description: Enrich leads and companies by internal or external identifiers.
  - name: 7. Email
    description: Find and validate email addresses.
  - name: 8. Accounts
    description: Account profile, usage, and transactions.
  - name: 9. Search
    description: Database and realtime lead, company, and company-lead search.
  - name: 10. Phone
    description: Find phone numbers for leads.
  - name: 11. Webhooks
    description: Register and manage async job notifications.
