openapi: 3.1.0
servers:
  - url: "https://app.fullenrich.com/api/v2"
info:
  title: FullEnrich API Documentation
  version: 2.0.0
  description: |
    FullEnrich API enables you to enrich B2B contacts with emails and phone numbers using data from 20+ providers.
    
    We are GDPR and CCPA compliant.

paths:
  /account/keys/verify:
    get:
      summary: Check If API Key Is Valid
      description: This endpoint checks if your API key is valid.
      operationId: checkKey
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/verifyKey"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                AuthorizationHeaderNotSet:
                  value:
                    code: error.authorization.not_set
                    message: Authorization headers not set
                AuthorizationHeaderNotAnBearer:
                  value:
                    code: error.authorization.not_bearer
                    message: Authorization headers do not have prefix 'bearer'
                UnknowApiKey:
                  value:
                    code: error.api.key
                    message: Unknown api key
        "404":
          description: Workspace ID not found
      security:
        - BearerAuth: []
  /account/credits:
    get:
      summary: Get Current Balance
      description: This endpoint provides the current balance of credits available in your workspace.
      operationId: getAccountCredits
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Credits"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                AuthorizationHeaderNotSet:
                  value:
                    code: error.authorization.not_set
                    message: Authorization headers not set
                AuthorizationHeaderNotAnBearer:
                  value:
                    code: error.authorization.not_bearer
                    message: Authorization headers do not have prefix 'bearer'
                UnknownApiKey:
                  value:
                    code: error.api.key
                    message: Unknown api key
        "404":
          description: Workspace ID not found
      security:
        - BearerAuth: []
  /contact/enrich/bulk:
    post:
      summary: Enrich Contacts In Bulk
      description: ""
      operationId: postContactBulkEnrich
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RequestPostContactBulkEnrich"
            example:
              name: "Sales Operations in London"
              webhook_url: "https://example.com/webhook"
              webhook_events:
                contact_finished: "https://example.com/webhook/contact"
              data:
                - first_name: "John"
                  last_name: "Snow"
                  domain: "example.com"
                  company_name: "Example Inc"
                  linkedin_url: "https://www.linkedin.com/in/demoge/"
                  enrich_fields:
                    - "contact.work_emails"
                    - "contact.personal_emails"
                    - "contact.phones"
                  custom:
                    user_id: "12584"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponsePostContactBulkEnrich"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                EnrichmentNameNotSet:
                  value:
                    code: error.enrichment.name.empty
                    message: Enrichment name not set
                WebhookURLInvalid:
                  value:
                    code: error.enrichment.webhook_url
                    message: Webhook URL must be start with http or https
                ProviderNotSet:
                  value:
                    code: error.enrichment.provider.empty
                    message: Providers not set
                DataNotSet:
                  value:
                    code: error.enrichment.data.empty
                    message: Data is empty
                FirstNameNotSet:
                  value:
                    code: error.enrichment.first_name.empty
                    message: First name cannot be empty
                LastNameNotSet:
                  value:
                    code: error.enrichment.last_name.empty
                    message: Last name cannot be empty
                DomainNotSet:
                  value:
                    code: error.enrichment.domain.empty
                    message: Domain cannot be empty
                EnrichFieldsNotSet:
                  value:
                    code: error.enrichment.enrich_fields.empty
                    message: enrichFields cannot be empty
                EnrichFieldValue:
                  value:
                    code: error.enrichment.enrich_field.value
                    message: enrichField 'xxxx' not valid must be contact.work_emails or contact.phones or contact.personal_emails
                CustomKeyExceeded:
                  value:
                    code: error.enrichment.custom.key.exceeded
                    message: "Custom field contains too many keys (max: 10 keys)"
                CustomKeyValueExceeded:
                  value:
                    code: error.enrichment.custom.value.exceeded
                    message: "Custom field value max len exceeded (max: 100 character)"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                AuthorizationHeaderNotSet:
                  value:
                    code: error.authorization.not_set
                    message: Authorization headers not set
                AuthorizationHeaderNotAnBearer:
                  value:
                    code: error.authorization.not_bearer
                    message: Authorization headers do not have prefix 'bearer'
                UnknownApiKey:
                  value:
                    code: error.api.key
                    message: Unknown api key
        "429":
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                RateLimitExceeded:
                  value:
                    code: error.rate.limit
                    message: Too many requests. Try again in 1m
      security:
        - BearerAuth: []
  "/contact/enrich/bulk/{enrichment_id}":
    get:
      summary: Get Bulk Enrich Results
      description: Use this endpoint to retrieve the result from an enrich.
      operationId: GetContactBulkEnrichByID
      parameters:
        - name: enrichment_id
          in: path
          required: true
          description: "The unique identifier returned when the enrichment was started"
          schema:
            type: string
          example: "2db5ea61-1752-42cf-8ea1-ab1da060cd0a"
        - name: forceResults
          in: query
          schema:
            type: boolean
          description: "Default = False. This parameter forces the API to return what has been found so far, even if the enrichment is not finished. This may result in missing information and is not recommended for regular use."
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponseGetContactBulkEnrich"
              example:
                id: "2db5ea61-1752-42cf-8ea1-ab1da060cd0a"
                name: "Sales Operations in London"
                status: "FINISHED"
                cost:
                  credits: 14
                data:
                  - input:
                      first_name: "John"
                      last_name: "Snow"
                      company_domain: "example.com"
                      company_name: "Example Inc"
                      professional_network_url: "https://www.linkedin.com/in/demoge/"
                    custom:
                      user_id: "12584"
                    contact_info:
                      most_probable_work_email:
                        email: "john.snow@example.com"
                        status: "DELIVERABLE"
                      most_probable_personal_email:
                        email: "johnsnow@gmail.com"
                        status: "DELIVERABLE"
                      most_probable_phone:
                        number: "+1 555-123-4567"
                        region: "US"
                      work_emails:
                        - email: "john.snow@example.com"
                          status: "DELIVERABLE"
                      personal_emails:
                        - email: "johnsnow@gmail.com"
                          status: "DELIVERABLE"
                      phones:
                        - number: "+1 555-123-4567"
                          region: "US"
                        - number: "+33 6 12 34 56 78"
                          region: "FR"
                    profile:
                      id: "746e4816-19c8-54d8-b558-65a5a52cc85c"
                      full_name: "John Snow"
                      first_name: "John"
                      last_name: "Snow"
                      headline: "Head of Sales Operations at Example Inc | Revenue Operations, CRM & Sales Enablement"
                      description: "Sales operations leader focused on revenue processes, CRM architecture and sales enablement. I help go-to-market teams scale pipeline with clean data and reliable reporting."
                      location:
                        country: "United States"
                        country_code: "US"
                        city: "San Francisco"
                        region: "California"
                      social_profiles:
                        professional_network:
                          id: 1234
                          url: 'https://www.linkedin.com/in/john-doe'
                          handle: john-doe
                          connection_count: 500
                      educations:
                        - school_name: Stanford University
                          degree: Bachelor of Science in Computer Science
                          start_at: '2015-09-01T00:00:00Z'
                          end_at: '2019-06-01T00:00:00Z'
                      languages:
                        - language: "English"
                          proficiency: "PROFESSIONAL_WORKING"
                        - language: "French"
                          proficiency: "NATIVE_OR_BILINGUAL"
                      skills:
                        - "Sales Operations"
                        - "Business Development"
                        - "CRM Management"
                      employment:
                        current:
                          title: "Head of Sales Operations"
                          is_current: true
                          start_at: "2022-03-15T00:00:00Z"
                          company:
                            id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                            name: "Example Inc"
                            domain: "example.com"
                            website: "https://www.example.com"
                            description: "Leading example company"
                            year_founded: 2010
                            headcount: 250
                            company_type: "Privately Held"
                            locations:
                              headquarters:
                                line1: "123 Market St"
                                line2: "San Francisco, CA 94105, US"
                                city: "San Francisco"
                                region: "California"
                                country: "United States"
                                country_code: "US"
                              offices:
                                - line1: "456 Broadway"
                                  line2: "New York, NY 10013, US"
                            industry:
                              main_industry: "Software Development"
                            social_profiles:
                              professional_network:
                                url: "https://www.linkedin.com/company/example-inc"
                                handle: "example-inc"
                                connection_count: 12000
                            logo_url: "https://app.fullenrich.com/logo/company/handle/example-inc"
                        all:
                          - title: "Head of Sales Operations"
                            is_current: true
                            start_at: "2022-03-15T00:00:00Z"
                            company:
                              id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                              name: "Example Inc"
                              domain: "example.com"
                              website: "https://www.example.com"
                              description: "Leading example company"
                              year_founded: 2010
                              headcount: 250
                              company_type: "Privately Held"
                              locations:
                                headquarters:
                                  line1: "123 Market St"
                                  line2: "San Francisco, CA 94105, US"
                                  city: "San Francisco"
                                  region: "California"
                                  country: "United States"
                                  country_code: "US"
                                offices:
                                  - line1: "456 Broadway"
                                    line2: "New York, NY 10013, US"
                              industry:
                                main_industry: "Software Development"
                              social_profiles:
                                professional_network:
                                  url: "https://www.linkedin.com/company/example-inc"
                                  handle: "example-inc"
                                  connection_count: 12000
                              logo_url: "https://app.fullenrich.com/logo/company/handle/example-inc"
                          - title: "Sales Manager"
                            is_current: false
                            start_at: "2019-07-01T00:00:00Z"
                            end_at: "2022-03-01T00:00:00Z"
                            company:
                              id: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                              name: "Previous Corp"
                              domain: "previouscorp.com"
                              website: "https://www.previouscorp.com"
                              description: "Enterprise software solutions"
                              year_founded: 2005
                              headcount: 500
                              company_type: "Privately Held"
                              locations:
                                headquarters:
                                  line1: "789 5th Ave"
                                  line2: "New York, NY 10022, US"
                                  city: "New York"
                                  region: "New York"
                                  country: "United States"
                                  country_code: "US"
                                offices: []
                              industry:
                                main_industry: "Software Development"
                              social_profiles:
                                professional_network:
                                  url: "https://www.linkedin.com/company/example-inc"
                                  handle: "example-inc"
                                  connection_count: 12000       
                              logo_url: "https://app.fullenrich.com/logo/company/handle/example-inc"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                InProgress:
                  value:
                    code: error.enrichment.in_progress
                    message: "Enrichment not ready, try again in 30 seconds"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                AuthorizationHeaderNotSet:
                  value:
                    code: error.authorization.not_set
                    message: Authorization headers not set
                AuthorizationHeaderNotAnBearer:
                  value:
                    code: error.authorization.not_bearer
                    message: Authorization headers do not have prefix 'bearer'
                UnknownApiKey:
                  value:
                    code: error.api.key
                    message: Unknown api key
        "402":
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponseGetContactBulkEnrich"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                EnrichmentNotFound:
                  value:
                    code: error.enrichment.not_found
                    message: Enrichment ID not found
        "429":
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                RateLimitExceeded:
                  value:
                    code: error.rate.limit
                    message: Too many requests. Try again in 1m
      security:
        - BearerAuth: []
  /contact/reverse/email/bulk:
    post:
      summary: Reverse Contact Lookup In Bulk
      description: ""
      operationId: postContactBulkReverseEmail
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RequestPostContactBulkReverseEmail"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponsePostContactBulkReverseEmail"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                ReverseEmailInvalid:
                  value:
                    code: error.reverse.email.invalid
                    message: Email is invalid
                ReverseEmailNotSet:
                  value:
                    code: error.reverse.email.empty
                    message: Email cannot be empty
                WebhookURLInvalid:
                  value:
                    code: error.enrichment.webhook_url
                    message: Webhook URL must be start with http or https
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                AuthorizationHeaderNotSet:
                  value:
                    code: error.authorization.not_set
                    message: Authorization headers not set
                AuthorizationHeaderNotAnBearer:
                  value:
                    code: error.authorization.not_bearer
                    message: Authorization headers do not have prefix 'bearer'
                UnknownApiKey:
                  value:
                    code: error.api.key
                    message: Unknown api key
      security:
        - BearerAuth: []
  "/contact/reverse/email/bulk/{enrichment_id}":
    get:
      summary: Get Bulk Reverse Email Results
      description: Use this endpoint to retrieve the result from a reverse email lookup.
      operationId: GetContactBulkReverseEmailByID
      parameters:
        - name: enrichment_id
          in: path
          required: true
          description: "The unique identifier returned when the reverse lookup was started"
          schema:
            type: string
          example: "2db5ea61-1752-42cf-8ea1-ab1da060cd0a"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponseGetContactBulkReverseEmail"
              example:
                id: "2db5ea61-1752-42cf-8ea1-ab1da060cd0a"
                name: "Reverse Email Lookup"
                status: "FINISHED"
                cost:
                  credits: 1
                data:
                  - input:
                      email: "johnsnow@gmail.com"
                    custom:
                      user_id: "12584"
                    profile:
                      id: "746e4816-19c8-54d8-b558-65a5a52cc85c"
                      full_name: "John Snow"
                      first_name: "John"
                      last_name: "Snow"
                      headline: "Head of Sales Operations at Example Inc | Revenue Operations, CRM & Sales Enablement"
                      description: "Sales operations leader focused on revenue processes, CRM architecture and sales enablement. I help go-to-market teams scale pipeline with clean data and reliable reporting."
                      location:
                        country: "United States"
                        country_code: "US"
                        city: "San Francisco"
                        region: "California"
                      social_profiles:
                        professional_network:
                          url: "https://www.linkedin.com/in/demoge/"
                          handle: "demoge"
                          connection_count: 500
                      educations:
                        - school_name: "Stanford University"
                          degree: "Bachelor of Science in Computer Science"
                          start_at: "2015-09-01T00:00:00Z"
                          end_at: "2019-06-01T00:00:00Z"
                      languages:
                        - language: "English"
                          proficiency: "PROFESSIONAL_WORKING"
                        - language: "French"
                          proficiency: "NATIVE_OR_BILINGUAL"
                      skills:
                        - "Sales Operations"
                        - "Business Development"
                        - "CRM Management"
                      employment:
                        current:
                          title: "Head of Sales Operations"
                          is_current: true
                          start_at: "2022-03-15T00:00:00Z"
                          company:
                            id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                            name: "Example Inc"
                            domain: "example.com"
                            website: "https://www.example.com"
                            description: "Leading example company"
                            year_founded: 2010
                            headcount: 250
                            company_type: "Privately Held"
                            locations:
                              headquarters:
                                line1: "123 Market St"
                                line2: "San Francisco, CA 94105, US"
                                city: "San Francisco"
                                region: "California"
                                country: "United States"
                                country_code: "US"
                              offices:
                                - line1: "456 Broadway"
                                  line2: "New York, NY 10013, US"
                            industry:
                              main_industry: "Software Development"
                            social_profiles:
                              professional_network:
                                url: "https://www.linkedin.com/company/example-inc"
                                handle: "example-inc"
                                connection_count: 12000
                            logo_url: "https://app.fullenrich.com/logo/company/handle/example-inc"
                        all:
                          - title: "Head of Sales Operations"
                            is_current: true
                            start_at: "2022-03-15T00:00:00Z"
                            company:
                              id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                              name: "Example Inc"
                              domain: "example.com"
                              website: "https://www.example.com"
                              description: "Leading example company"
                              year_founded: 2010
                              headcount: 250
                              company_type: "Privately Held"
                              locations:
                                headquarters:
                                  line1: "123 Market St"
                                  line2: "San Francisco, CA 94105, US"
                                  city: "San Francisco"
                                  region: "California"
                                  country: "United States"
                                  country_code: "US"
                                offices:
                                  - line1: "456 Broadway"
                                    line2: "New York, NY 10013, US"
                              industry:
                                main_industry: "Software Development"
                              social_profiles:
                                professional_network:
                                  url: "https://www.linkedin.com/company/example-inc"
                                  handle: "example-inc"
                                  connection_count: 12000
                              logo_url: "https://app.fullenrich.com/logo/company/handle/example-inc"
                          - title: "Sales Manager"
                            is_current: false
                            start_at: "2019-07-01T00:00:00Z"
                            end_at: "2022-03-01T00:00:00Z"
                            company:
                              id: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                              name: "Previous Corp"
                              domain: "previouscorp.com"
                              website: "https://www.previouscorp.com"
                              description: "Enterprise software solutions"
                              year_founded: 2005
                              headcount: 500
                              company_type: "Privately Held"
                              locations:
                                headquarters:
                                  line1: "789 5th Ave"
                                  line2: "New York, NY 10022, US"
                                  city: "New York"
                                  region: "New York"
                                  country: "United States"
                                  country_code: "US"
                                offices: []
                              industry:
                                main_industry: "Software Development"
                              social_profiles:
                                professional_network:
                                  url: "https://www.linkedin.com/company/previous-corp"
                                  handle: "previous-corp"
                                  connection_count: 8000
                              logo_url: "https://app.fullenrich.com/logo/company/handle/previous-corp"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                AuthorizationHeaderNotSet:
                  value:
                    code: error.authorization.not_set
                    message: Authorization headers not set
                AuthorizationHeaderNotAnBearer:
                  value:
                    code: error.authorization.not_bearer
                    message: Authorization headers do not have prefix 'bearer'
                UnknownApiKey:
                  value:
                    code: error.api.key
                    message: Unknown api key
        "402":
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponseGetContactBulkReverseEmail"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                ReverseEmailNotFound:
                  value:
                    code: error.reverse.email.not_found
                    message: Reverse email ID not found
      security:
        - BearerAuth: []
  /people/search:
    post:
      summary: "Search people"
      description: "Search for people based on various filters. Multiple filters within the same field are combined with AND logic."
      operationId: "postPeopleSearch"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchPeopleRequest"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                allOf:
                - $ref: "#/components/schemas/SearchPeopleResponse"
                - $ref: "#/components/schemas/Metadata"
        "400":
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                AuthorizationHeaderNotSet:
                  value:
                    code: "error.authorization.not_set"
                    message: "Authorization headers not set"
                AuthorizationHeaderNotAnBearer:
                  value:
                    code: "error.authorization.not_bearer"
                    message: "Authorization headers do not have prefix 'bearer'"
                UnknownApiKey:
                  value:
                    code: "error.api.key"
                    message: "Unknown api key"
        "429":
          description: "Too Many Requests"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                RateLimitExceeded:
                  value:
                    code: "error.rate.limit"
                    message: "Too many requests. Try again in 1m"
      security:
        - BearerAuth: []
  /company/search:
    post:
      summary: "Search company"
      description: "Search for companies based on various filters. Multiple filters within the same field are combined with AND logic."
      operationId: "postCompanySearch"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchCompanyRequest"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                allOf:
                - $ref: "#/components/schemas/SearchCompanyResponse"
                - $ref: "#/components/schemas/Metadata"
        "400":
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                AuthorizationHeaderNotSet:
                  value:
                    code: "error.authorization.not_set"
                    message: "Authorization headers not set"
                AuthorizationHeaderNotAnBearer:
                  value:
                    code: "error.authorization.not_bearer"
                    message: "Authorization headers do not have prefix 'bearer'"
                UnknownApiKey:
                  value:
                    code: "error.api.key"
                    message: "Unknown api key"
        "429":
          description: "Too Many Requests"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                RateLimitExceeded:
                  value:
                    code: "error.rate.limit"
                    message: "Too many requests. Try again in 1m"
      security:
        - BearerAuth: []
  /people/lookup:
    post:
      summary: "Look up people"
      description: "Look up a single person using their identifiers (professional network URL/ID, or full name combined with a company identifier). Returns the best matching person."
      operationId: "postPeopleLookup"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LookUpPeopleRequest"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                allOf:
                - $ref: "#/components/schemas/LookUpPeopleResponse"
                - $ref: "#/components/schemas/LookUpMetadata"
        "400":
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                AuthorizationHeaderNotSet:
                  value:
                    code: "error.authorization.not_set"
                    message: "Authorization headers not set"
                AuthorizationHeaderNotAnBearer:
                  value:
                    code: "error.authorization.not_bearer"
                    message: "Authorization headers do not have prefix 'bearer'"
                UnknownApiKey:
                  value:
                    code: "error.api.key"
                    message: "Unknown api key"
        "429":
          description: "Too Many Requests"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                RateLimitExceeded:
                  value:
                    code: "error.rate.limit"
                    message: "Too many requests. Try again in 1m"
      security:
        - BearerAuth: []
  /company/lookup:
    post:
      summary: "Look up company"
      description: "Look up a single company using its identifiers (domain, or professional network URL/ID). Returns the best matching company."
      operationId: "postCompanyLookup"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LookUpCompanyRequest"
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                allOf:
                - $ref: "#/components/schemas/LookUpCompanyResponse"
                - $ref: "#/components/schemas/LookUpMetadata"
        "400":
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                AuthorizationHeaderNotSet:
                  value:
                    code: "error.authorization.not_set"
                    message: "Authorization headers not set"
                AuthorizationHeaderNotAnBearer:
                  value:
                    code: "error.authorization.not_bearer"
                    message: "Authorization headers do not have prefix 'bearer'"
                UnknownApiKey:
                  value:
                    code: "error.api.key"
                    message: "Unknown api key"
        "429":
          description: "Too Many Requests"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                RateLimitExceeded:
                  value:
                    code: "error.rate.limit"
                    message: "Too many requests. Try again in 1m"
      security:
        - BearerAuth: []

components:
  schemas:
    verifyKey:
      type: object
      description: "Response returned when API key is valid"
      properties:
        workspace_id:
          type: string
          description: "The workspace ID associated with this API key"
          example: "2db5ea61-1752-42cf-8ea1-ab1da060cd0a"
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
    Credits:
      type: object
      properties:
        balance:
          type: number
          format: double
          description: Number of credits available on your workspace
          examples:
            - 5000
    RecordEnrichment:
      type: object
      description: "A single enriched contact record"
      properties:
        input:
          description: "The original input data provided for this contact"
          $ref: "#/components/schemas/ContactEnrichmentInput"
        custom:
          type: object
          description: "Custom fields passed during enrichment request, returned unchanged"
          examples:
            - user_id: "12584"
        contact_info:
          description: "Contact information found during enrichment (emails and phone numbers)"
          $ref: "#/components/schemas/ContactEnrichedInformation"
        profile:
          description: "Full professional profile of the person (returned when linkedin_url was provided)"
          $ref: "#/components/schemas/Person"
    ContactEnrichmentInput:
      type: object
      description: "The input data originally provided for this contact enrichment"
      properties:
        first_name:
          type: string
          description: "First name of the contact"
          examples:
            - John
        last_name:
          type: string
          description: "Last name of the contact"
          examples:
            - Snow
        full_name:
          type: string
          description: "Full name of the contact"
          examples:
            - John Snow
        company_domain:
          type: string
          description: "Domain of the contact's company"
          examples:
            - example.com
        company_name:
          type: string
          description: "Name of the contact's company"
          examples:
            - Example Inc
        professional_network_url:
          type: string
          description: "Professional network profile URL of the contact"
          examples:
            - https://www.linkedin.com/in/demoge
    ContactEnrichedInformation:
      type: object
      description: "Contact information found during enrichment"
      properties:
        most_probable_work_email:
          description: "The most reliable work email found"
          $ref: "#/components/schemas/Email"
        most_probable_personal_email:
          description: "The most reliable personal email found"
          $ref: "#/components/schemas/Email"
        most_probable_phone:
          description: "The most reliable mobile phone number found"
          $ref: "#/components/schemas/Phone"
        work_emails:
          type: array
          description: "All work emails found"
          items:
            $ref: "#/components/schemas/Email"
        personal_emails:
          type: array
          description: "All personal emails found"
          items:
            $ref: "#/components/schemas/Email"
        phones:
          type: array
          description: "All mobile phone numbers found"
          items:
            $ref: "#/components/schemas/Phone"
    Email:
      type: object
      properties:
        email:
          type: string
          examples:
            - john.snow@example.com
        status:
          type: string
          examples:
            - DELIVERABLE
          enum:
            - DELIVERABLE
            - HIGH_PROBABILITY
            - CATCH_ALL
            - INVALID
            - INVALID_DOMAIN
    Phone:
      type: object
      properties:
        number:
          type: string
          description: "Phone number in international format (E.164)"
          examples:
            - +33 6 76 78 90 65
        region:
          type: string
          description: "ISO 3166-1 alpha-2 country code where the phone number is registered (e.g., FR for France, US for United States)"
          examples:
            - FR
    RequestPostContactBulkEnrich:
      type: object
      example:
        name: "Sales Operations in London"
        webhook_url: "https://example.com/webhook"
        webhook_events:
          contact_finished: "https://example.com/webhook/contact"
        data:
          - first_name: "John"
            last_name: "Snow"
            domain: "example.com"
            company_name: "Example Inc"
            professional_network_url: "https://www.linkedin.com/in/demoge/"
            enrich_fields:
              - "contact.work_emails"
              - "contact.personal_emails"
              - "contact.phones"
            custom:
              user_id: "12584"
      properties:
        name:
          type: string
          description: "A readable name for this enrichment (visible in your dashboard)"
        webhook_url:
          type: string
          description: "URL that will receive a POST request when the entire enrichment is finished (all contacts processed)."
        webhook_events:
          type: object
          description: "Optional webhook URLs for specific events during enrichment"
          properties:
            contact_finished:
              type: string
              description: "URL that receives a POST request each time a single contact is enriched, without waiting for the entire batch to complete. Useful for real-time updates."
        data:
          type: array
          items:
            $ref: "#/components/schemas/RequestPostContactBulkEnrichContact"
      required:
        - name
        - data
    RequestPostContactBulkEnrichContact:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        domain:
          type: string
        company_name:
          type: string
        linkedin_url:
          type: string
          description: "Supports standard LinkedIn profile URLs (e.g., https://www.linkedin.com/in/demoge) as well as LinkedIn Sales Navigator URLs (e.g., https://www.linkedin.com/in/ACwAACLLwaIBKi655883b)."
        enrich_fields:
          type: array
          items:
            type: string
            enum:
              - contact.work_emails
              - contact.phones
              - contact.personal_emails
        custom:
          type: object
          description: "Returned in the enrichment result. Use it to identify a user, a CRM contact, or to pass any other information. All values must be strings. Limited to 20 entries."
    ResponsePostContactBulkEnrich:
      type: object
      properties:
        enrichment_id:
          type: string
          format: uuid
          examples:
            - 2db5ea61-1752-42cf-8ea1-ab1da060cd0a
    ResponseGetContactBulkEnrich:
      type: object
      properties:
        id:
          type: string
          format: uuid
          examples:
            - 2db5ea61-1752-42cf-8ea1-ab1da060cd0a
        name:
          type: string
          examples:
            - Sales Operations in London
        status:
          type: string
          examples:
            - FINISHED
          enum:
            - CREATED
            - IN_PROGRESS
            - CANCELED
            - CREDITS_INSUFFICIENT
            - FINISHED
            - RATE_LIMIT
            - UNKNOWN
        data:
          type: array
          items:
            $ref: "#/components/schemas/RecordEnrichment"
        cost:
          $ref: "#/components/schemas/Cost"
    RequestPostContactBulkReverseEmail:
      type: object
      properties:
        name:
          type: string
          description: "A readable name for this reverse lookup (visible in your dashboard)"
          example: "Reverse Lookup Batch 1"
        webhook_url:
          type: string
          description: "URL that will receive a POST request when the entire reverse lookup is finished (all emails processed)."
          example: "https://example.com/webhook"
        webhook_events:
          type: object
          description: "Optional webhook URLs for specific events during reverse lookup"
          properties:
            contact_finished:
              type: string
              description: "URL that receives a POST request each time a single email is processed, without waiting for the entire batch to complete."
              example: "https://example.com/webhook/contact"
        data:
          type: array
          items:
            type: object
            properties:
              email:
                type: string
                description: "Email address to perform reverse lookup on"
                example: "john.snow@example.com"
              custom:
                type: object
                description: "Custom fields returned in the result (max 10 keys, 100 chars per value)"
                example:
                  user_id: "12584"
            required:
              - email
          example:
            - email: "john.snow@example.com"
              custom:
                user_id: "12584"
      required:
        - name
        - data
    ResponsePostContactBulkReverseEmail:
      type: object
      properties:
        enrichment_id:
          type: string
          format: uuid
          examples:
            - 2db5ea61-1752-42cf-8ea1-ab1da060cd0a
    ResponseGetContactBulkReverseEmail:
      type: object
      properties:
        id:
          type: string
          format: uuid
          examples:
            - 2db5ea61-1752-42cf-8ea1-ab1da060cd0a
        name:
          type: string
          examples:
            - Start Reverse Email Lookup Operation
        status:
          type: string
          examples:
            - FINISHED
          enum:
            - CREATED
            - IN_PROGRESS
            - CANCELED
            - CREDITS_INSUFFICIENT
            - FINISHED
            - RATE_LIMIT
            - UNKNOWN
        data:
          type: array
          items:
            $ref: "#/components/schemas/RecordReverseEmail"
        cost:
          $ref: "#/components/schemas/Cost"
    RecordReverseEmail:
      type: object
      properties:
        input:
          $ref: "#/components/schemas/ContactReverseEmailInput"
        custom:
          type: object
          examples:
            - user_id: "12584"
        profile:
          $ref: "#/components/schemas/Person"
    ContactReverseEmailInput:
      type: object
      properties:
        email:
          type: string
          examples:
            - john.snow@example.com
    Cost:
      type: object
      properties:
        credits:
          type: integer
          format: int64
          description: Number of credits consumed for this enrichment
          examples:
            - 1
            - 0
    SearchPeopleRequest:
      type: object
      properties:
        offset:
          type: integer
          description: "Number of people to skip (use this for pagination). Maximum value is 10,000. To paginate beyond 10,000 results, use search_after instead."
          example: 0
        limit:
          type: integer
          description: "Number of people to return (default: 10, max: 100)"
          example: 20
        search_after:
          type: string
          description: "Cursor-based pagination. Pass the search_after value from the previous response to get the next page. Works at any point in the result set, but is required to access results beyond the 10,000 offset limit. The search_after token does not have any expiration date. However, when the database is updated (every month), if the position of a contact changes, the same search_after token might display different results."
          example: "WzE1LjUzNDU2MywiYjQ5MDBiYmQtOTg5MS01Mzk1LWIyODUtOWEyOGNiZThjOTM3Il0="
        current_company_names:
          type: array
          description: "Filter by current company names. Use exact_match for precise company name matching."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "Anthropic"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: true
          example:
            - value: "Anthropic"
              exact_match: true
              exclude: false
            - value: "OpenAI"
              exact_match: true
              exclude: false
        current_company_domains:
          type: array
          description: "Filter by current company domains (e.g., 'google.com', 'microsoft.com'). Exact match recommended for domains."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "google.com"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: true
          example:
            - value: "google.com"
              exact_match: true
              exclude: false
        current_company_professional_network_ids:
          type: array
          description: "Filter by current company professional network IDs."
          items:
            type: object
            properties:
              value:
                type: integer
                description: "The integer value to filter by"
                example: 1234
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the exact term must appear within the value, but can still be part of a longer string. When false (default), matching is flexible and tolerates slight variations such as missing or extra words. Matching is never case-sensitive."
                example: true
          example:
            - value: 1234
              exact_match: true
              exclude: false
        current_company_professional_network_urls:
          type: array
          description: "Filter by current company professional network URLs."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "https://www.linkedin.com/company/fullenrich"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: true
          example:
            - value: "https://www.linkedin.com/company/fullenrich"
              exact_match: true
              exclude: false
        current_company_specialties:
          type: array
          description: "Filter by current company specialties."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "artificial intelligence"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: true
          example:
            - value: "artificial intelligence"
              exact_match: true
              exclude: false
        current_company_industries:
          type: array
          description: "Filter by company industries (e.g., 'Software Development', 'Computer Hardware Manufacturing', 'Housing and Community Development', 'Warehousing'). See [Industries](/api/v2/general/enums#company-industry) for the full list."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "Software Development"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: false
          example:
            - value: "Software Development"
              exact_match: false
              exclude: false
            - value: "Computer Hardware Manufacturing"
              exact_match: false
              exclude: false
        current_company_technologies:
          type: array
          description: "Filter by technologies used by the current company (e.g., 'Notion', 'Salesforce', 'AWS')."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "Notion"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: false
          example:
            - value: "Notion"
              exact_match: false
              exclude: false
        past_company_names:
          type: array
          description: "Filter by past company names. Useful for finding people with specific work history."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "Meta"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: true
          example:
            - value: "Meta"
              exact_match: true
              exclude: false
        past_company_domains:
          type: array
          description: "Filter by past company domains"
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "facebook.com"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: true
          example:
            - value: "facebook.com"
              exact_match: true
              exclude: false
        current_company_types:
          type: array
          description: "Filter by company types (e.g., 'Public Company', 'Privately Held', 'Nonprofit', 'Self-Employed', 'Partnership', 'Educational', 'Government Agency'). See [Company Types](/api/v2/general/enums#company-type) for the full list."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "Public Company"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: true
          example:
            - value: "Public Company"
              exact_match: true
              exclude: false
        current_company_headquarters:
          type: array
          description: "Filter by company headquarters locations (city names, regions, or countries)"
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "San Francisco"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: false
          example:
            - value: "San Francisco"
              exact_match: false
              exclude: false
            - value: "New York"
              exact_match: false
              exclude: false
        current_company_headcounts:
          type: array
          description: "Filter by company size (number of employees). Use ranges to target specific company sizes."
          items:
            type: object
            properties:
              min:
                type: integer
                description: "Minimum number of employees (inclusive)"
                example: 50
              max:
                type: integer
                description: "Maximum number of employees (inclusive)"
                example: 500
              exclude:
                type: boolean
                description: "If true, excludes companies in this range"
                example: false
          example:
            - min: 50
              max: 200
              exclude: false
            - min: 1000
              max: 5000
              exclude: false
        # FE-2892: company revenue temporarily disabled
        # current_company_revenue_ranges:
        #   type: array
        #   description: "Filter by the current company's annual revenue brackets. See [Company Revenue](/api/v2/general/enums#company-revenue) for the full list of accepted values."
        #   items:
        #     type: object
        #     properties:
        #       value:
        #         type: string
        #         description: "The revenue bracket to filter by. Must be one of the accepted values (e.g., '$1M-$2M', '$10M-$50M', '>$1B')."
        #         example: "$10M-$50M"
        #       exclude:
        #         type: boolean
        #         description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
        #         example: false
        #   example:
        #     - value: "$10M-$50M"
        #       exclude: false
        #     - value: "$50M-$100M"
        #       exclude: false
        current_company_founded_years:
          type: array
          description: "Filter by company founding year. Useful for targeting startups or established companies."
          items:
            type: object
            properties:
              min:
                type: integer
                description: "Minimum founding year (inclusive)"
                example: 2015
              max:
                type: integer
                description: "Maximum founding year (inclusive)"
                example: 2024
              exclude:
                type: boolean
                description: "If true, excludes companies founded in this range"
                example: false
          example:
            - min: 2020
              max: 2024
              exclude: false
        current_company_ids:
          type: array
          description: "Filter by specific company IDs"
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: true
        person_ids:
          type: array
          description: "Filter by specific person IDs"
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "746e4816-19c8-54d8-b558-65a5a52cc85c"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: true
        person_names:
          type: array
          description: "Filter by person names (first name, last name, or full name)"
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "John Smith"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: false
          example:
            - value: "John Smith"
              exact_match: false
              exclude: false
        person_professional_network_ids:
          type: array
          description: "Filter by person professional network IDs."
          items:
            type: object
            properties:
              value:
                type: integer
                description: "The integer value to filter by"
                example: 1234
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the exact term must appear within the value, but can still be part of a longer string. When false (default), matching is flexible and tolerates slight variations such as missing or extra words. Matching is never case-sensitive."
                example: true
          example:
            - value: 1234
              exact_match: true
              exclude: false
        person_professional_network_urls:
          type: array
          description: "Filter by person professional network URLs."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "https://www.linkedin.com/in/john-doe"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: true
          example:
            - value: "https://www.linkedin.com/in/john-doe"
              exact_match: true
              exclude: false
        person_locations:
          type: array
          description: "Filter by person locations (city, region, or country)"
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "San Francisco"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: false
          example:
            - value: "San Francisco"
              exact_match: false
              exclude: false
            - value: "California"
              exact_match: false
              exclude: false
        person_languages:
          type: array
          description: "Filter by languages spoken by the person"
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "English"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: false
          example:
            - value: "English"
              exact_match: false
              exclude: false
            - value: "French"
              exact_match: false
              exclude: false
        person_skills:
          type: array
          description: "Filter by skills (e.g., 'JavaScript', 'Python', 'Project Management')"
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "JavaScript"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: false
          example:
            - value: "JavaScript"
              exact_match: false
              exclude: false
            - value: "Python"
              exact_match: false
              exclude: false
            - value: "Project Management"
              exact_match: false
              exclude: false
        current_position_seniority_level:
          type: array
          description: "Filter by person seniority levels (e.g., 'Owner', 'Founder', 'C-level', 'Partner', 'VP', 'Head', 'Director', 'Senior', 'Manager'). See [Seniority Levels](/api/v2/general/enums#seniority) for the full list."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "Director"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: false
          example:
            - value: "Director"
              exact_match: false
              exclude: false
            - value: "VP"
              exact_match: false
              exclude: false
        current_position_job_functions:
          type: array
          description: "Filter by current job functions (e.g., 'Administrative', 'Agriculture & Environment', 'Construction & Trades', ...). See [Functions & Subfunctions](/api/v2/general/enums#functions-and-subfunctions) for the full list."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "Software Development"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: false
          example:
            - value: "Software Development"
              exact_match: false
              exclude: false
        current_position_sub_functions:
          type: array
          description: "Filter by current sub functions (e.g., 'Data Entry', 'Agriculture/Landscaping', 'Carpenter'). See [Functions & Subfunctions](/api/v2/general/enums#functions-and-subfunctions) for the full list."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "Freelancer"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: false
          example:
            - value: "Freelancer"
              exact_match: false
              exclude: false
        current_position_titles:
          type: array
          description: "Filter by current job titles (e.g., 'Software Engineer', 'Product Manager', 'CEO')"
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "Chief Technology Officer"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: false
          example:
            - value: "Chief Technology Officer"
              exact_match: false
              exclude: false
            - value: "VP of Engineering"
              exact_match: false
              exclude: false
        past_position_titles:
          type: array
          description: "Filter by past job titles. Useful for finding people who held specific roles."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "Software Engineer"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: false
          example:
            - value: "Software Engineer"
              exact_match: false
              exclude: false
        current_position_years_in:
          type: array
          description: "Filter by years spent in current position. Useful for targeting people new in role or experienced."
          items:
            type: object
            properties:
              min:
                type: integer
                description: "Minimum years in current position (inclusive)"
                example: 0
              max:
                type: integer
                description: "Maximum years in current position (inclusive)"
                example: 2
              exclude:
                type: boolean
                description: "If true, excludes people in this range"
                example: false
          example:
            - min: 0
              max: 1
              exclude: false
        current_company_years_at:
          type: array
          description: "Filter by years at current company (tenure). Useful for targeting new hires or long-term employees."
          items:
            type: object
            properties:
              min:
                type: integer
                description: "Minimum years at current company (inclusive)"
                example: 1
              max:
                type: integer
                description: "Maximum years at current company (inclusive)"
                example: 5
              exclude:
                type: boolean
                description: "If true, excludes people in this range"
                example: false
          example:
            - min: 2
              max: 5
              exclude: false
        # current_company_keywords:
        #   type: array
        #   description: "Filter by description of current company"
        #   items:
        #     $ref: "#/components/schemas/StringFilter"
        #   example:
        #     - value: "innovative and practical products"
        #       exact_match: false
        #       exclude: false              
        person_universities:
          type: array
          description: "Filter by universities attended (e.g., 'Stanford University', 'MIT', 'Harvard')"
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "Stanford University"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: false
          example:
            - value: "Stanford University"
              exact_match: false
              exclude: false
            - value: "MIT"
              exact_match: false
              exclude: false
        current_company_days_since_last_job_change:
          type: array
          description: "Filter by days since last job change. Useful for finding people who recently changed jobs."
          items:
            type: object
            properties:
              min:
                type: integer
                description: "Minimum days since last job change (inclusive)"
                example: 0
              max:
                type: integer
                description: "Maximum days since last job change (inclusive)"
                example: 90
              exclude:
                type: boolean
                description: "If true, excludes people in this range"
                example: false
          example:
            - min: 0
              max: 90
              exclude: false
    SearchPeopleResponse:
      type: object
      properties:
        people:
          type: array
          description: "Array of people matching the search criteria. Returns empty array if no results found."
          items:
            $ref: "#/components/schemas/Person"
    Person:
      type: object
      properties: 
        id:
          type: string
          description: "Unique person identifier"
          example: "746e4816-19c8-54d8-b558-65a5a52cc85c"
        full_name:
          type: string
          description: "Person's full name"
          example: "Enzo Romera"
        first_name:
          type: string
          description: "Person's first name"
          example: "Enzo"
        last_name:
          type: string
          description: "Person's last name"
          example: "Romera"
        headline:
          type: string
          description: "Short professional tagline written by the person on their professional network profile"
          example: "Marketing Strategist | 10+ Years in Strategy, Account Management & Activation | Consulting Expert"
        description:
          type: string
          description: "Free-text summary written by the person in the about section of their professional network profile. Omitted when not available."
          example: "Marketing strategist with 10+ years helping B2B companies build demand generation engines. I work with go-to-market teams on positioning, account-based campaigns and channel activation."
        location:
          type: object
          description: "Person's location information"
          properties: 
            country:
              type: string
              description: "Country name"
              example: "United States"
            country_code:
              type: string
              description: "ISO country code"
              example: "US"
            city:
              type: string
              description: "City name"
              example: "San Francisco"
            region:
              type: string
              description: "Region or state"
              example: "California"
        social_profiles:
          type: object
          description: "Person's social media profiles"
          allOf:
          - $ref: "#/components/schemas/PersonSocialProfile"
        educations:
          type: array
          description: "Person's education history"
          items:
            $ref: "#/components/schemas/PersonEducation"
        languages:
          type: array
          description: "Languages spoken by the person"
          items:
            $ref: "#/components/schemas/PersonLanguage"
        skills:
          type: array
          description: "Person's professional skills"
          items:
            type: string
          example:
            - "JavaScript"
            - "Project Management"
            - "Python"
        employment:
          type: object
          description: "Person's employment history"
          properties:
            current:
              type: object
              description: "Current employment information. If the person is in their current position, the end_at field will not be returned."
              allOf:
              - $ref: "#/components/schemas/Employment"
            all:
              type: array
              description: "All employment history (current and past)"
              items:
                $ref: "#/components/schemas/Employment"
    PersonSocialProfile:
      type: object
      properties: 
        professional_network:
          type: object
          description: "Professional network profile information"
          properties: 
            id:
              type: integer
              description: "Professional network profile ID"
              example: 1234
            url:
              type: string
              description: "Full professional network profile URL"
              example: "https://www.linkedin.com/in/john-doe"
            handle:
              type: string
              description: "Professional network profile handle/username"
              example: "john-doe"
            connection_count:
              type: integer
              description: "Number of professional network connections"
              example: 500
    CompanySocialProfile:
      type: object
      properties: 
        professional_network:
          type: object
          description: "Professional network profile information"
          properties: 
            id:
              type: integer
              description: "Professional network profile ID"
              example: 1234
            url:
              type: string
              description: "Full professional network profile URL"
              example: "https://www.linkedin.com/company/anthropic"
            handle:
              type: string
              description: "Professional network profile handle/username"
              example: "anthropic"
            connection_count:
              type: integer
              description: "Number of professional network followers"
              example: 125000
    PersonEducation:
      type: object
      properties: 
        school_name:
          type: string
          description: "Name of the educational institution"
          example: "Stanford University"
        degree:
          type: string
          description: "Degree or qualification obtained"
          example: "Bachelor of Science in Computer Science"
        start_at:
          type: string
          format: date-time
          description: "Start date in ISO 8601 format with T separator (YYYY-MM-DDTHH:MM:SSZ)"
          example: "2015-09-01T00:00:00Z"
        end_at:
          type: string
          format: date-time
          description: "End date in ISO 8601 format with T separator (YYYY-MM-DDTHH:MM:SSZ)"
          example: "2019-06-01T00:00:00Z"
    PersonLanguage:
      type: object
      properties: 
        language:
          type: string
          description: "Language name"
          example: "French"
        proficiency:
          type: string
          description: "Proficiency level in the language (e.g., 'NATIVE_OR_BILINGUAL', 'FULL_PROFESSIONAL', 'PROFESSIONAL_WORKING', 'LIMITED_WORKING', 'ELEMENTARY')"
          example: "NATIVE_OR_BILINGUAL"
    EmploymentCompany:
      type: object
      properties:
        id:
          type: string
          description: "Unique company identifier"
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        name:
          type: string
          description: "Company name"
          example: "Anthropic"
        domain:
          type: string
          description: "Company domain"
          example: "anthropic.com"
        website:
          type: string
          description: "Company website URL as declared by the company. May differ from `domain` (can include a subdomain, a path or tracking parameters). Omitted when not available."
          example: "https://www.anthropic.com"
        description:
          type: string
          description: "Company description"
          example: "AI safety and research company"
        year_founded:
          type: integer
          description: "Year the company was founded. Returns 0 when unknown."
          example: 2021
        headcount:
          type: integer
          description: "Exact number of employees. May return 0 even when headcount_range is available."
          example: 2610
        headcount_range:
          type: string
          description: "Employee count range (e.g., '1-10', '11-50', '51-200', '201-500', '501-1000', '1001-5000', '5001-10000', '10001+')"
          example: "1001-5000"
        company_type:
          type: string
          description: "Type of company (e.g., 'Public Company', 'Privately Held', 'Nonprofit', 'Self-Employed', 'Partnership', 'Educational', 'Government Agency')"
          example: "Privately Held"
        specialties:
          type: array
          description: "Specialties associated with the company"
          items:
            type: string
          example:
            - "Data Enrichment"
            - "B2B Data"
        technologies:
          type: array
          description: "Technologies used by the company"
          items:
            type: object
            properties:
              name:
                type: string
                description: "Technology name"
                example: "Fullenrich"
              logo_url:
                type: string
                description: "URL of the technology logo"
                example: "https://app.fullenrich.com/logo/technologies/id/3uwxkma9y03lj"
          example:
            - name: "Fullenrich"
              logo_url: "https://app.fullenrich.com/logo/technologies/id/3uwxkma9y03lj"
        locations:
          type: object
          description: "Company location information"
          properties: 
            headquarters:
              type: object
              description: "Main headquarters address with structured location fields. Can be an empty object when no headquarters data is available."
              allOf:
              - $ref: '#/components/schemas/CompanyAddress'
            offices:
              type: array
              description: "Additional office locations. Only contains raw address lines (line1, line2) without structured city/region/country fields. Can be null or an empty array."
              nullable: true
              items:
                $ref: '#/components/schemas/OfficeAddress'
        industry:
          type: object
          description: "Company industry information"
          properties:
            main_industry:
              type: string
              description: "Primary industry category (e.g., 'Software Development', 'Computer Hardware Manufacturing', 'Financial Services', 'Healthcare')"
              example: "Software Development"
        social_profiles:
          type: object
          description: "Company's social media profiles"
          allOf:
          - $ref: "#/components/schemas/CompanySocialProfile"
        logo_url:
          type: string
          description: "URL of the company logo hosted by FullEnrich, built from the company's professional network handle. Empty when the handle is unknown."
          example: "https://app.fullenrich.com/logo/company/handle/anthropic"
        # FE-2892: company revenue temporarily disabled
        # revenue_range:
        #   type: string
        #   description: "Annual revenue bracket. Omitted when unknown. See [Company Revenue](/api/v2/general/enums#company-revenue) for the full list of possible values."
        #   example: "$10M-$50M"
    Employment:
      type: object
      properties:
        title:
          type: string
          description: "Job title or position"
          example: "Senior Software Engineer"
        seniority:
          type: string
          description: "Seniority level of the person in the company"
          example: "Senior"
        job_functions:
          type: array
          description: "Job functions of the person in the company"
          items:
            type: object
            properties:
              function:
                type: string
                description: "Job function"
                example: "Not Employed"
              sub_function:
                type: string
                description: "Sub function of the job function"
                example: "Freelancer"
        description:
          type: string
          description: "Description of the role and responsibilities. Not always present."
          example: "Leading the backend team and designing microservices architecture."
        company:
          type: object
          description: "Company information"
          allOf:
          - $ref: "#/components/schemas/EmploymentCompany"
        is_current:
          type: boolean
          description: "Whether this is the current employment"
          example: true
        start_at:
          type: string
          format: date-time
          description: "Employment start date in ISO 8601 format with T separator (YYYY-MM-DDTHH:MM:SSZ)"
          example: "2022-03-15T00:00:00Z"
        end_at:
          type: string
          format: date-time
          description: "Employment end date in ISO 8601 format with T separator (YYYY-MM-DDTHH:MM:SSZ). This field is not returned for current employment (when is_current is true)."
          example: "2024-06-30T00:00:00Z"
    SearchCompanyRequest:
      type: object
      properties:
        offset:
          type: integer
          description: "Number of companies to skip (use this for pagination). Maximum value is 10,000. To paginate beyond 10,000 results, use search_after instead."
          example: 20
        limit:
          type: integer
          description: "Number of companies to return (default: 10, max: 100)"
          example: 20
        search_after:
          type: string
          description: "Cursor-based pagination. Pass the search_after value from the previous response to get the next page. Works at any point in the result set, but is required to access results beyond the 10,000 offset limit. The search_after token does not have any expiration date. However, when the database is updated (every month), if the position of a company changes, the same search_after token might display different results."
          example: "WzE1LjUzNDU2MywiYjQ5MDBiYmQtOTg5MS01Mzk1LWIyODUtOWEyOGNiZThjOTM3Il0="
        names:
          type: array
          description: "Filter by company names. Use exact_match for precise company name matching."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "Microsoft"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: true
          example:
            - value: "Microsoft"
              exact_match: true
              exclude: false
        domains:
          type: array
          description: "Filter by company domains (e.g., 'google.com', 'microsoft.com'). Exact match recommended."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "microsoft.com"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: true
          example:
            - value: "microsoft.com"
              exact_match: true
              exclude: false
        professional_network_ids:
          type: array
          description: "Filter by professional network IDs."
          items:
            type: object
            properties:
              value:
                type: integer
                description: "The integer value to filter by"
                example: 1234
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the exact term must appear within the value, but can still be part of a longer string. When false (default), matching is flexible and tolerates slight variations such as missing or extra words. Matching is never case-sensitive."
                example: true
          example:
            - value: 1234
              exact_match: true
              exclude: false
        professional_network_urls:
          type: array
          description: "Filter by professional network URLs."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "https://www.linkedin.com/company/fullenrich"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: true
          example:
            - value: "https://www.linkedin.com/company/fullenrich"
              exact_match: true
              exclude: false
        keywords:
          type: array
          description: "Filter by description of company"
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "innovative and practical products"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: false
          example:
            - value: "innovative and practical products"
              exact_match: false
              exclude: false
        specialties:
          type: array
          description: "Filter by specialties of company"
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "AI safety"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: false
          example:
            - value: "AI safety"
              exact_match: false
              exclude: false
        technologies:
          type: array
          description: "Filter by technologies used by the company (e.g., 'Notion', 'Fullenrich', 'AWS')."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "Notion"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: false
          example:
            - value: "Fullenrich"
              exact_match: false
              exclude: false
        industries:
          type: array
          description: "Filter by company industries (e.g., 'Software Development', 'Computer Hardware Manufacturing', 'Housing and Community Development', 'Warehousing', 'Financial Services'). See [Industries](/api/v2/general/enums#company-industry) for the full list."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "Software Development"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: false
          example:
            - value: "Software Development"
              exact_match: false
              exclude: false
            - value: "Computer Hardware Manufacturing"
              exact_match: false
              exclude: false
        types:
          type: array
          description: "Filter by company types (e.g., 'Public Company', 'Privately Held', 'Nonprofit', 'Self-Employed', 'Partnership', 'Educational', 'Government Agency'). See [Company Types](/api/v2/general/enums#company-type) for the full list."
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "Public Company"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: true
          example:
            - value: "Public Company"
              exact_match: true
              exclude: false
        headquarters_locations:
          type: array
          description: "Filter by headquarters locations (city names, regions, or countries)"
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "San Francisco"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: false
          example:
            - value: "San Francisco"
              exact_match: false
              exclude: false
        founded_years:
          type: array
          description: "Filter by founding years. Useful for targeting startups (recent years) or established companies."
          items:
            type: object
            properties:
              min:
                type: integer
                description: "Minimum founding year (inclusive)"
                example: 2010
              max:
                type: integer
                description: "Maximum founding year (inclusive)"
                example: 2024
              exclude:
                type: boolean
                description: "If true, excludes companies founded in this range"
                example: false
          example:
            - min: 2015
              max: 2024
              exclude: false
        headcounts:
          type: array
          description: "Filter by company headcounts (number of employees). Use ranges to target specific company sizes (e.g., startups: 1-50, mid-size: 50-500, enterprise: 1000+)."
          items:
            type: object
            properties:
              min:
                type: integer
                description: "Minimum number of employees (inclusive)"
                example: 100
              max:
                type: integer
                description: "Maximum number of employees (inclusive)"
                example: 1000
              exclude:
                type: boolean
                description: "If true, excludes companies in this range"
                example: false
          example:
            - min: 100
              max: 500
              exclude: false
        # FE-2892: company revenue temporarily disabled
        # revenue_ranges:
        #   type: array
        #   description: "Filter by company annual revenue brackets. See [Company Revenue](/api/v2/general/enums#company-revenue) for the full list of accepted values."
        #   items:
        #     type: object
        #     properties:
        #       value:
        #         type: string
        #         description: "The revenue bracket to filter by. Must be one of the accepted values (e.g., '$1M-$2M', '$10M-$50M', '>$1B')."
        #         example: "$10M-$50M"
        #       exclude:
        #         type: boolean
        #         description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
        #         example: false
        #   example:
        #     - value: "$10M-$50M"
        #       exclude: false
        #     - value: "$50M-$100M"
        #       exclude: false
        company_ids:
          type: array
          description: "Filter by specific company IDs"
          items:
            type: object
            properties:
              value:
                type: string
                description: "The string value to filter by"
                example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
              exclude:
                type: boolean
                description: "If true, excludes results matching this value. If false or omitted (default), includes only matching results."
                example: false
              exact_match:
                type: boolean
                description: "When true, the value must match exactly as stored (case-insensitive), with no tolerance for variations. When false (default), the API tolerates minor differences such as missing words, extra words, or slight reordering. Matching is never case-sensitive."
                example: true
    SearchCompanyResponse:
      type: object
      properties:
        companies:
          type: array
          description: "Array of companies matching the search criteria. Returns empty array if no results found."
          items:
            $ref: "#/components/schemas/Company"
    Company:
      type: object
      properties: 
        id:
          type: string
          description: "Unique company identifier"
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        name:
          type: string
          description: "Company name"
          example: "Anthropic"
        domain:
          type: string
          description: "Company domain"
          example: "anthropic.com"
        website:
          type: string
          description: "Company website URL as declared by the company. May differ from `domain` (can include a subdomain, a path or tracking parameters). Omitted when not available."
          example: "https://www.anthropic.com"
        description:
          type: string
          description: "Company description"
          example: "AI safety and research company building reliable, interpretable, and steerable AI systems."
        year_founded:
          type: integer
          description: "Year the company was founded. Returns 0 when unknown."
          example: 2021
        headcount:
          type: integer
          description: "Exact number of employees. May return 0 even when headcount_range is available."
          example: 2610
        headcount_range:
          type: string
          description: "Employee count range (e.g., '1-10', '11-50', '51-200', '201-500', '501-1000', '1001-5000', '5001-10000', '10001+')"
          example: "1001-5000"
        company_type:
          type: string
          description: "Type of company (e.g., 'Public Company', 'Privately Held', 'Nonprofit', 'Self-Employed', 'Partnership', 'Educational', 'Government Agency')"
          example: "Privately Held"
        locations:
          type: object
          description: "Company location information"
          properties: 
            headquarters:
              type: object
              description: "Main headquarters address with structured location fields. Can be an empty object when no headquarters data is available."
              allOf:
              - $ref: '#/components/schemas/CompanyAddress'
            offices:
              type: array
              description: "Additional office locations. Only contains raw address lines (line1, line2) without structured city/region/country fields. Can be null or an empty array."
              nullable: true
              items:
                $ref: '#/components/schemas/OfficeAddress'
        social_profiles:
          type: object
          description: "Company's social media profiles"
          allOf:
          - $ref: "#/components/schemas/CompanySocialProfile"
        specialties:
          type: array
          description: "Specialties associated with the company"
          items:
            type: string
          example:
            - "artificial intelligence"
            - "machine learning"
            - "AI safety"
        technologies:
          type: array
          description: "Technologies used by the company"
          items:
            type: object
            properties:
              name:
                type: string
                description: "Technology name"
                example: "Fullenrich"
              logo_url:
                type: string
                description: "URL of the technology logo"
                example: "https://app.fullenrich.com/logo/technologies/id/3uwxkma9y03lj"
          example:
            - name: "Fullenrich"
              logo_url: "https://app.fullenrich.com/logo/technologies/id/3uwxkma9y03lj"
        industry:
          type: object
          description: "Company industry information"
          properties:
            main_industry:
              type: string
              description: "Primary industry category (e.g., 'Software Development', 'Computer Hardware Manufacturing', 'Financial Services', 'Healthcare', 'Retail')"
              example: "Software Development"
        logo_url:
          type: string
          description: "URL of the company logo hosted by FullEnrich, built from the company's professional network handle. Empty when the handle is unknown."
          example: "https://app.fullenrich.com/logo/company/handle/anthropic"
        # FE-2892: company revenue temporarily disabled
        # revenue_range:
        #   type: string
        #   description: "Annual revenue bracket. Omitted when unknown. See [Company Revenue](/api/v2/general/enums#company-revenue) for the full list of possible values."
        #   example: "$10M-$50M"
    CompanyAddress:
      type: object
      description: "Structured headquarters address with parsed location fields"
      properties: 
        line1:
          type: string
          description: "Address line 1 (street address)"
          example: "548 Market St"
        line2: 
          type: string
          description: "Address line 2 (full location string including city, region, postal code, and country code)"
          example: "San Francisco, CA 94105, US"
        city:
          type: string
          description: "City name"
          example: "San Francisco"
        region:
          type: string
          description: "State or region"
          example: "California"
        country:
          type: string
          description: "Country name"
          example: "United States"
        country_code:
          type: string
          description: "ISO country code"
          example: "US"
    OfficeAddress:
      type: object
      description: "Office address. Unlike headquarters, office addresses only contain raw address lines without parsed location fields."
      properties:
        line1:
          type: string
          description: "Street address"
          example: "111 8th Ave"
        line2:
          type: string
          description: "Full location string (city, region, postal code, country code)"
          example: "New York, NY 10011, US"
    LookUpPeopleRequest:
      type: object
      description: "Provide at least one identifier to match a single person. The professional network URL or ID is the most reliable. A full name can be combined with a company identifier (domain, professional network URL, or professional network ID) to disambiguate the match."
      properties:
        person_name:
          type: string
          description: "Full name of the person to look up."
          example: "Enzo Romera"
        person_professional_network_url:
          type: string
          description: "Professional network profile URL of the person."
          example: "https://www.linkedin.com/in/enzo-romera"
        person_professional_network_id:
          type: integer
          description: "Professional network profile ID of the person."
          example: 530992355
        company_professional_network_url:
          type: string
          description: "Professional network URL of the company the person works for. Used to disambiguate when looking up by name."
          example: "https://www.linkedin.com/company/anthropic"
        company_professional_network_id:
          type: integer
          description: "Professional network ID of the company the person works for. Used to disambiguate when looking up by name."
          example: 1883877
        company_domain:
          type: string
          description: "Domain of the company the person works for. Used to disambiguate when looking up by name."
          example: "anthropic.com"
    LookUpPeopleResponse:
      type: object
      properties:
        people:
          type: array
          description: "Array containing the matching person. Returns an empty array if no match is found."
          items:
            $ref: "#/components/schemas/Person"
    LookUpCompanyRequest:
      type: object
      description: "Provide at least one identifier to match a single company. The domain or professional network URL/ID give the most reliable match."
      properties:
        domain:
          type: string
          description: "Company domain to look up."
          example: "anthropic.com"
        professional_network_url:
          type: string
          description: "Professional network URL of the company."
          example: "https://www.linkedin.com/company/anthropic"
        professional_network_id:
          type: integer
          description: "Professional network ID of the company."
          example: 1883877
    LookUpCompanyResponse:
      type: object
      properties:
        companies:
          type: array
          description: "Array containing the matching company. Returns an empty array if no match is found."
          items:
            $ref: "#/components/schemas/Company"
    LookUpMetadata:
      type: object
      properties:
        metadata:
          type: object
          properties:
            credits:
              type: number
              format: double
              description: "Total number of credits consumed"
              example: 0.25
    Metadata:
      type: object
      properties:
        metadata:
          type: object
          properties:
            total:
              type: integer
              description: "Total number of results matching the search criteria"
              example: 20523
            credits:
              type: number
              format: double
              description: "Total number of credits consumed"
              example: 22.5
            offset:
              type: integer
              description: "Number of results skipped (for pagination)"
              example: 0
            search_after:
              type: string
              description: "The cursor value returned by the previous page. Use this to paginate through the results."
              example: "WzE1LjUzNDU2MywiYjQ5MDBiYmQtOTg5MS01Mzk1LWIyODUtOWEyOGNiZThjOTM3Il0="

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: string