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

# Search candidate profiles

> Search for candidate profiles from external sources using a natural language query. Results include a session ID for use with the ingest endpoint. Configure options to control data freshness and whether to reveal contact information. Billable — charges a base fee (`sourcing_search_fast`, or `sourcing_search_pro` when `options.search_type` is `pro`), plus per-candidate premiums for any enabled options (`sourcing_insights`, `sourcing_high_freshness`) and per-revealed-contact fees (`sourcing_reveal_email`, `sourcing_reveal_phone`). The balance is prechecked against the worst case; paginating a cached `session_id` costs no tokens. See `GET /tokens/costs` for live pricing.



## OpenAPI

````yaml /api-reference/openapi.json post /sourcing/search
openapi: 3.1.0
info:
  title: Fribl API
  description: >-
    The Fribl API enables intelligent talent matching powered by AI. Analyze CVs
    and job descriptions from text or file uploads, search and manage skills,
    match candidates to positions with configurable scoring weights, and source
    candidate profiles from external databases. All document processing is
    asynchronous — submit documents for analysis, poll for status, and retrieve
    structured results when ready.
  version: 1.0.0
  contact:
    name: Fribl Support
    url: https://fribl.co
servers:
  - url: https://api-service.fribl.co/api/v1
    description: Production
security:
  - apiKey: []
tags:
  - name: CVs
    description: >-
      Upload, analyze, retrieve, update, and delete candidate CVs. CVs can be
      submitted as raw text or as PDF file uploads. Processing is asynchronous —
      use the status endpoint to track progress.
  - name: Jobs
    description: >-
      Upload, analyze, retrieve, update, and delete job descriptions. Jobs can
      be submitted as raw text or as PDF file uploads. Processing is
      asynchronous — use the status endpoint to track progress.
  - name: Matching
    description: >-
      Match analyzed CVs against job descriptions using AI-powered scoring.
      Configure weights across experience, hard skills, soft skills, and
      education dimensions to tailor match results to your hiring priorities.
  - name: Sourcing
    description: >-
      Search for candidate profiles from external sources, retrieve cached
      search results, and ingest selected profiles into your Fribl workspace for
      matching.
  - name: Skills
    description: >-
      Search the Fribl skills taxonomy and retrieve available languages for
      skill translation. These endpoints are publicly accessible and do not
      require authentication.
  - name: Tokens
    description: >-
      Inspect your workspace's usage-based token balance, review the ledger of
      every charge and refund, and read the live per-action price list. Billable
      endpoints deduct tokens and return 402 when the balance is insufficient.
      Tokens are purchased and managed in the Fribl Console
      (https://console.fribl.co).
paths:
  /sourcing/search:
    post:
      tags:
        - Sourcing
      summary: Search candidate profiles
      description: >-
        Search for candidate profiles from external sources using a natural
        language query. Results include a session ID for use with the ingest
        endpoint. Configure options to control data freshness and whether to
        reveal contact information. Billable — charges a base fee
        (`sourcing_search_fast`, or `sourcing_search_pro` when
        `options.search_type` is `pro`), plus per-candidate premiums for any
        enabled options (`sourcing_insights`, `sourcing_high_freshness`) and
        per-revealed-contact fees (`sourcing_reveal_email`,
        `sourcing_reveal_phone`). The balance is prechecked against the worst
        case; paginating a cached `session_id` costs no tokens. See `GET
        /tokens/costs` for live pricing.
      operationId: searchCandidateProfiles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourcingSearchBody'
      responses:
        '200':
          description: Search results with candidate profiles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourcingSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
components:
  schemas:
    SourcingSearchBody:
      type: object
      description: Request body for searching candidate profiles from external sources.
      properties:
        query:
          type: string
          description: Natural language search query describing the ideal candidate.
        options:
          type: object
          description: Search options to control result quality and data exposure.
          properties:
            high_freshness:
              type: boolean
              description: Prioritize recently updated profiles.
            reveal_emails:
              type: boolean
              description: Include email addresses in results where available.
            reveal_phones:
              type: boolean
              description: Include phone numbers in results where available.
        pagination:
          type: object
          description: Pagination settings for the search results.
          properties:
            limit:
              type: integer
              minimum: 1
              maximum: 100
              default: 25
              description: Maximum number of results per page.
            offset:
              type: integer
              description: Number of results to skip.
      required:
        - query
    SourcingSearchResponse:
      type: object
      description: Response from a sourcing search operation.
      properties:
        session_id:
          type: string
          description: Session identifier for paginating through these results.
        results:
          type: array
          items:
            $ref: '#/components/schemas/SourcingResultItem'
          description: Array of candidate search result objects.
        pagination:
          type: object
          description: Pagination metadata for the search results.
          properties:
            total_estimate:
              type: integer
              description: Estimated total number of matching profiles.
            offset:
              type: integer
              description: Number of results skipped.
            limit:
              type: integer
              description: Maximum results per page.
            has_more:
              type: boolean
              description: Whether additional pages of results are available.
          required:
            - total_estimate
            - offset
            - limit
            - has_more
      required:
        - session_id
        - results
        - pagination
    SourcingResultItem:
      type: object
      description: >-
        A single search result containing a candidate profile with optional
        relevance scoring.
      properties:
        docid:
          type: string
          description: Document identifier, typically a LinkedIn slug.
          example: john-doe-a1b2c3d4
        profile:
          $ref: '#/components/schemas/SourcingCandidateProfile'
        score:
          type:
            - number
            - 'null'
          description: Relevance score for this result.
        insights:
          type:
            - object
            - 'null'
          description: Additional AI-generated insights about the candidate's fit.
      required:
        - docid
        - profile
    ErrorResponse:
      type: object
      description: Standard error response.
      properties:
        error:
          type: string
          description: Human-readable error message.
      required:
        - error
    InsufficientTokensError:
      type: object
      description: >-
        Returned with HTTP 402 when the workspace balance can't cover a billable
        request. No work is performed and nothing is charged.
      properties:
        code:
          type: string
          enum:
            - INSUFFICIENT_TOKENS
          description: Machine-readable error code. Switch on this rather than the message.
          example: INSUFFICIENT_TOKENS
        message:
          type: string
          example: 'Insufficient tokens: have 3, need 10'
        balance:
          type: integer
          description: Current workspace balance.
          example: 3
        required:
          type: integer
          description: Tokens required for this request (worst case for sourcing searches).
          example: 10
      required:
        - code
        - message
        - balance
        - required
    SourcingCandidateProfile:
      type: object
      description: A rich candidate profile from external sourcing data.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the profile.
        docid:
          type: string
          description: Document identifier, typically a LinkedIn slug.
          example: john-doe-a1b2c3d4
        linkedin_slug:
          type:
            - string
            - 'null'
          description: LinkedIn profile slug.
          example: john-doe-a1b2c3d4
        first_name:
          type:
            - string
            - 'null'
          description: Candidate's first name.
          example: John
        last_name:
          type:
            - string
            - 'null'
          description: Candidate's last name.
          example: Doe
        picture_url:
          type:
            - string
            - 'null'
          description: URL of the candidate's profile picture.
        title:
          type:
            - string
            - 'null'
          description: Current professional title.
          example: Senior Software Engineer at Acme Corp
        summary:
          type:
            - string
            - 'null'
          description: Professional summary or bio.
        gender:
          type:
            - string
            - 'null'
          description: Candidate's gender.
          example: male
        is_decision_maker:
          type:
            - integer
            - 'null'
          description: Whether the candidate is a decision maker (0 or 1).
        languages:
          type: array
          items:
            $ref: '#/components/schemas/SourcingLanguage'
          description: Languages listed on the candidate's profile.
        inferred_languages:
          type: array
          items:
            $ref: '#/components/schemas/SourcingLanguage'
          description: Languages inferred from the candidate's profile data.
        location:
          type:
            - string
            - 'null'
          description: Candidate's location.
          example: Amsterdam, Netherlands
        location_coordinates:
          $ref: '#/components/schemas/SourcingCoordinates'
        is_top_universities:
          type:
            - boolean
            - 'null'
          description: Whether the candidate attended a top-ranked university.
        total_experience_years:
          type:
            - number
            - 'null'
          description: Total years of professional experience.
          example: 8
        estimated_age:
          type:
            - number
            - 'null'
          description: Estimated age of the candidate.
          example: 32
        expertise:
          type: array
          items:
            type: string
          description: List of expertise areas and keywords.
          example:
            - python
            - machine-learning
            - cloud
        has_phone_numbers:
          type:
            - boolean
            - 'null'
          description: Whether phone numbers are available for this candidate.
        has_emails:
          type:
            - boolean
            - 'null'
          description: Whether email addresses are available for this candidate.
        followers_count:
          type:
            - integer
            - 'null'
          description: Number of LinkedIn followers.
          example: 500
        connections_count:
          type:
            - integer
            - 'null'
          description: Number of LinkedIn connections.
          example: 350
        experiences:
          type: array
          items:
            $ref: '#/components/schemas/SourcingCompanyExperienceGroup'
          description: Work experience grouped by company.
        educations:
          type: array
          items:
            $ref: '#/components/schemas/SourcingEducation'
          description: List of education entries.
        certifications:
          type: array
          items:
            $ref: '#/components/schemas/SourcingCertification'
          description: List of professional certifications.
        publications:
          type: array
          items:
            $ref: '#/components/schemas/SourcingPublication'
          description: List of publications authored by the candidate.
        updated_date:
          type:
            - string
            - 'null'
          description: Date when the profile was last updated.
          example: '2024-06-15'
        business_emails:
          type: array
          items:
            type: string
            format: email
          description: >-
            Business email addresses (available when reveal_emails option is
            enabled).
        personal_emails:
          type: array
          items:
            type: string
            format: email
          description: >-
            Personal email addresses (available when reveal_emails option is
            enabled).
          example:
            - john.doe@email.com
    SourcingLanguage:
      type: object
      description: A language entry with proficiency level.
      properties:
        language:
          type:
            - string
            - 'null'
          description: Language name.
          example: English
        proficiency:
          type:
            - string
            - 'null'
          description: Proficiency level (e.g., native, professional, B2, unknown).
          example: native
    SourcingCoordinates:
      type: object
      description: Geographic coordinates.
      properties:
        lat:
          type:
            - number
            - 'null'
          description: Latitude.
          example: 52.4
        lng:
          type:
            - number
            - 'null'
          description: Longitude.
          example: 4.9
    SourcingCompanyExperienceGroup:
      type: object
      description: A group of roles held at the same company, with company metadata.
      properties:
        company_info:
          $ref: '#/components/schemas/SourcingCompanyInfo'
        company_roles:
          type: array
          items:
            $ref: '#/components/schemas/SourcingCompanyRole'
          description: List of roles held at this company, ordered by start date.
        type:
          type: string
          description: Entry type identifier.
          example: company-experiences
    SourcingEducation:
      type: object
      description: An education entry from a sourced candidate profile.
      properties:
        university_linkedin_url:
          type:
            - string
            - 'null'
          description: LinkedIn URL of the university.
          example: https://www.linkedin.com/school/mit
        campus:
          type:
            - string
            - 'null'
          description: Name of the institution or campus.
          example: MIT
        degree:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Degree(s) obtained or pursued.
          example:
            - master
        major:
          type:
            - string
            - 'null'
          description: Full field of study description.
          example: Master of Science, Computer Science
        start_date:
          type:
            - string
            - 'null'
          description: Start date in YYYY-MM-DD format.
          example: '2018-09-01'
        end_date:
          type:
            - string
            - 'null'
          description: End date in YYYY-MM-DD format.
          example: '2020-06-01'
        research:
          type:
            - string
            - 'null'
          description: Research intensity classification of the institution.
          example: VH
        status:
          type:
            - string
            - 'null'
          description: Institution status (e.g., Public, Private).
          example: Public
        focus:
          type:
            - string
            - 'null'
          description: >-
            Academic focus classification (e.g., CO for comprehensive, FO for
            focused).
          example: CO
        rank:
          type:
            - string
            - 'null'
          description: University ranking position.
          example: '251'
        score:
          type:
            - number
            - 'null'
          description: University quality score.
          example: 50.2
        size:
          type:
            - string
            - 'null'
          description: University size classification (e.g., S, M, L, XL).
          example: L
        country:
          type:
            - string
            - 'null'
          description: Country where the institution is located.
          example: United States
    SourcingCertification:
      type: object
      description: A professional certification.
      properties:
        title:
          type:
            - string
            - 'null'
          description: Certification title.
          example: AWS Solutions Architect
    SourcingPublication:
      type: object
      description: A publication authored by the candidate.
      properties:
        title:
          type:
            - string
            - 'null'
          description: Publication title.
          example: Machine Learning in Modern Applications
        issue:
          type:
            - string
            - 'null'
          description: Journal, conference, or publication venue.
          example: IEEE
        date:
          type:
            - string
            - 'null'
          description: Publication date in YYYY-MM-DD format.
          example: '2021-03-15'
    SourcingCompanyInfo:
      type: object
      description: Detailed information about a company from external sources.
      properties:
        name:
          type:
            - string
            - 'null'
          description: Company name.
          example: Acme Corp
        unique_name:
          type:
            - string
            - 'null'
          description: Unique normalized company name.
        domain:
          type:
            - string
            - 'null'
          description: Company website domain.
          example: acme-corp.com
        website:
          type:
            - string
            - 'null'
          description: Company website URL.
          example: https://www.acme-corp.com
        linkedin_url:
          type:
            - string
            - 'null'
          description: Company LinkedIn page URL.
          example: https://www.linkedin.com/company/acme-corp
        linkedin_slug:
          type:
            - string
            - 'null'
          description: Company LinkedIn slug identifier.
          example: acme-corp
        crunchbase_url:
          type:
            - string
            - 'null'
          description: Company Crunchbase profile URL.
        social_urls:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Social media profile URLs.
        short_address:
          type:
            - string
            - 'null'
          description: Abbreviated company address.
          example: Amsterdam, NL
        locations:
          type:
            - array
            - 'null'
          items:
            type: string
          description: List of office locations.
        type:
          type:
            - string
            - 'null'
          description: Entry type identifier.
          example: company-info
        description:
          type:
            - string
            - 'null'
          description: Company description or tagline.
        industries:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Industries the company operates in.
          example:
            - Technology
        specialties:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Company specialties or areas of expertise.
        keywords:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Keywords associated with the company.
        technologies:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Technologies used by the company.
        founded_in:
          type:
            - integer
            - 'null'
          description: Year the company was founded.
          example: 2020
        num_employees:
          type:
            - integer
            - 'null'
          description: Approximate number of employees.
          example: 150
        num_employees_range:
          type:
            - string
            - 'null'
          description: Employee count range.
          example: 51-200
        annual_revenue:
          type:
            - number
            - 'null'
          description: Estimated annual revenue in USD.
          example: 5000000
        followers_count:
          type:
            - integer
            - 'null'
          description: Number of LinkedIn followers.
          example: 5000
        funding_total_usd:
          type:
            - number
            - 'null'
          description: Total funding raised in USD.
          example: 50000000
        last_funding_round_year:
          type:
            - integer
            - 'null'
          description: Year of the most recent funding round.
          example: 2023
        is_startup:
          type:
            - boolean
            - 'null'
          description: Whether the company is classified as a startup.
        has_ipo:
          type:
            - boolean
            - 'null'
          description: Whether the company has had an IPO.
        is_b2b:
          type:
            - boolean
            - 'null'
          description: Whether the company operates in B2B.
        is_b2c:
          type:
            - boolean
            - 'null'
          description: Whether the company operates in B2C.
        is_saas:
          type:
            - boolean
            - 'null'
          description: Whether the company is a SaaS provider.
        is_hiring:
          type:
            - boolean
            - 'null'
          description: Whether the company is currently hiring.
        backed_by_y_combinator:
          type:
            - boolean
            - 'null'
          description: Whether the company is backed by Y Combinator.
        icon:
          type:
            - string
            - 'null'
          description: URL of the company logo or icon.
    SourcingCompanyRole:
      type: object
      description: A specific role held at a company.
      properties:
        company:
          type:
            - string
            - 'null'
          description: Company name.
          example: Acme Corp
        company_domain:
          type:
            - string
            - 'null'
          description: Company website domain.
          example: acme-corp.com
        title:
          type:
            - string
            - 'null'
          description: Job title for this role.
          example: Senior Software Engineer
        start_date:
          type:
            - string
            - 'null'
          description: Role start date in YYYY-MM-DD format.
          example: '2023-01-15'
        end_date:
          type:
            - string
            - 'null'
          description: >-
            Role end date in YYYY-MM-DD format. Null if this is the current
            role.
        duration_years:
          type:
            - number
            - 'null'
          description: Duration of the role in years.
          example: 2.5
        age_years:
          type:
            - number
            - 'null'
          description: How long ago the role ended (or started if current) in years.
          example: 0
        location:
          type:
            - string
            - 'null'
          description: Location of the role.
          example: Amsterdam, Netherlands
        location_info:
          $ref: '#/components/schemas/SourcingLocationInfo'
        experience_summary:
          type:
            - string
            - 'null'
          description: Summary of role responsibilities and achievements.
        is_current_experience:
          type:
            - boolean
            - 'null'
          description: Whether this is the candidate's current role.
    SourcingLocationInfo:
      type:
        - object
        - 'null'
      description: Location details including coordinates and country code.
      properties:
        lat:
          type:
            - number
            - 'null'
          description: Latitude.
          example: 52.4
        lng:
          type:
            - number
            - 'null'
          description: Longitude.
          example: 4.9
        country_code:
          type:
            - string
            - 'null'
          description: ISO 3166-1 alpha-2 country code.
          example: NL
  responses:
    BadRequest:
      description: The request was malformed or contained invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: >-
        Authentication failed. Provide a valid API key in the `x-api-key`
        header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PaymentRequired:
      description: >-
        The workspace has insufficient tokens for the requested operation.
        Nothing was charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InsufficientTokensError'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key in UUID format. Include this header with every authenticated
        request.

````