> ## Documentation Index > Fetch the complete documentation index at: https://docs.companyenrich.com/llms.txt > Use this file to discover all available pages before exploring further. # Enrich a person by email > **Cost:** 5 credits when a person is returned, plus requested paid expansions. The `education` expansion adds 1 credit per returned person. Repeating an expansion does not multiply its cost. The `company` expansion includes the standard company profile in `experiences[].company` for current and past experiences. It adds 1 credit per unique company successfully expanded. Unavailable companies retain their summary without an expansion charge. Separately priced company expansions are not included. Company expansion is limited to 500 unique available companies per request. Exceeding the limit returns `400` without charging credits; remove `company` from `expand` to retrieve the person without company profiles. Resolves the company from the email domain, then matches the person using common email address patterns such as `first.last` or `flast`. Returns the best match, with the experience at the email's company marked as `isMatched`. Returns `404` without charging credits when no person matches the email address. ## OpenAPI ````yaml openapi/v2.json POST /v2/people/enrich openapi: 3.0.4 info: title: Company Enrich API v2 description: >- The Company Enrich API v2 provides programmatic access to company and person data for enrichment, search, and lead generation. ## Key Features - **Company Enrichment** — Enrich company profiles by domain or identifying properties, and retrieve stored companies by ID. - **Company Search** — Search and filter companies with cursor pagination, counts, and previews. - **Semantic and Lookalike Search** — Find companies using natural-language queries or similar company domains. - **People Enrichment** — Retrieve people by ID, identify people from their email address, and find work email addresses. - **People Search** — Search people by position, seniority, department, location, education, and company with cursor pagination, counts, and previews. - **Reference Data** — Look up industries, geographic data, keywords, technologies, and job titles. V2 intentionally excludes saved company lists, list-based exports, and filtering searches by saved-list IDs. These features remain available in V1 and are not planned for V2. ## Authentication All API requests require a Bearer token passed in the `Authorization` header: ``` Authorization: Bearer YOUR_API_TOKEN ``` You can generate API tokens from your [dashboard](https://companyenrich.com/dashboard). ## Credits Most API calls consume credits. The credit cost for each endpoint is documented in its description. You can check your remaining credit balance using the User endpoint. ## Rate Limiting The global API limiter allows **500 requests per minute** per IP address. Authenticated API routes also use a per-user route limiter based on plan capabilities. Supplementary lookup endpoints (such as keyword/technology/industry autocompletes) use a separate per-user route-level bucket. termsOfService: https://companyenrich.com/terms-and-conditions contact: url: https://companyenrich.com/ email: support@companyenrich.com version: 2.0.0 servers: - url: https://api.companyenrich.com security: - Bearer: [] tags: - name: Company / Enrichment description: >- Enrich company data by domain, properties, or in batch. Get company details by ID. - name: Company / Bulk Enrichment description: >- Create and manage asynchronous bulk enrichment jobs for large domain lists. - name: Company / Search description: Search companies by filters with pagination and cursor scrolling. - name: People / Search description: >- Search people by various criteria with page-based or cursor-based pagination. - name: People / Enrichment description: >- Resolve work email addresses for individual people in realtime or background jobs. - name: Geo description: >- Endpoints for looking up geographic data including regions, countries, states, and cities. - name: Industries description: >- Endpoints for listing available industry classifications used in company search filters. - name: Keywords description: Endpoints for looking up keywords used in company search filters. - name: Technologies description: Endpoints for looking up technologies used in company search filters. - name: User description: >- Endpoints for retrieving information about the authenticated user, including credit balance and account details. - name: Positions description: Endpoints for looking up job positions and titles. paths: /v2/people/enrich: post: tags: - People / Enrichment summary: Enrich a person by email description: >- **Cost:** 5 credits when a person is returned, plus requested paid expansions. The `education` expansion adds 1 credit per returned person. Repeating an expansion does not multiply its cost. The `company` expansion includes the standard company profile in `experiences[].company` for current and past experiences. It adds 1 credit per unique company successfully expanded. Unavailable companies retain their summary without an expansion charge. Separately priced company expansions are not included. Company expansion is limited to 500 unique available companies per request. Exceeding the limit returns `400` without charging credits; remove `company` from `expand` to retrieve the person without company profiles. Resolves the company from the email domain, then matches the person using common email address patterns such as `first.last` or `flast`. Returns the best match, with the experience at the email's company marked as `isMatched`. Returns `404` without charging credits when no person matches the email address. requestBody: content: application/json: schema: $ref: '#/components/schemas/PersonEnrichV2Request' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PersonResponse' '400': description: Bad Request content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '402': description: Payment Required content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '404': description: Not Found content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '422': description: Unprocessable Entity content: application/problem+json: schema: $ref: '#/components/schemas/HttpValidationProblemDetails' '429': description: Too Many Requests content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' components: schemas: PersonEnrichV2Request: required: - email type: object properties: email: maxLength: 320 type: string description: The email address of the person expand: type: array items: enum: - education - company type: string description: >- Additional person data to include, charged on top of the base cost. Repeating an expansion does not multiply its cost: - `education`: 1 credit per returned person. - `company`: 1 credit per unique company successfully expanded across the returned current and past experiences. Includes the standard company profile; separately priced company expansions are not included. Unavailable companies retain their summary without an expansion charge. Search charges each company once per response page. Limited to 500 unique available companies per request; exceeding the limit returns `400` without charging credits. Reduce `pageSize` for searches or remove `company` from `expand`. nullable: true PersonResponse: required: - id - socials - experiences type: object properties: id: type: integer description: The CompanyEnrich ID of the person format: int64 name: type: string description: The full name of the person nullable: true firstName: type: string description: The first name of the person nullable: true lastName: type: string description: The last name of the person nullable: true imageUrl: type: string description: The person image URL nullable: true position: type: string description: The person's current position or title nullable: true seniority: $ref: '#/components/schemas/NullableOfPersonSeniority' department: $ref: '#/components/schemas/NullableOfPersonDepartment' location: $ref: '#/components/schemas/PersonLocationResponse' socials: $ref: '#/components/schemas/PersonSocialsResponse' experiences: type: array items: $ref: '#/components/schemas/PersonExperienceResponse' description: The person's work experience updatedAt: type: string description: When the person data was last updated format: date-time nullable: true education: type: array items: $ref: '#/components/schemas/PersonEducationResponse' description: >- The person's education history. Included when `education` is requested in `expand`. nullable: true ProblemDetails: type: object properties: type: type: string nullable: true title: type: string nullable: true status: type: integer format: int32 nullable: true detail: type: string nullable: true instance: type: string nullable: true HttpValidationProblemDetails: type: object properties: type: type: string nullable: true title: type: string nullable: true status: type: integer format: int32 nullable: true detail: type: string nullable: true instance: type: string nullable: true errors: type: object additionalProperties: type: array items: type: string NullableOfPersonSeniority: enum: - owner - founder - c-suite - partner - vp - head - director - manager - senior - entry - intern - null description: The person's current seniority level nullable: true NullableOfPersonDepartment: enum: - c-suite - c-suite/executive - c-suite/finance-executive - c-suite/founder - c-suite/human-resources-executive - c-suite/information-technology-executive - c-suite/legal-executive - c-suite/marketing-executive - c-suite/medical-health-executive - c-suite/operations-executive - c-suite/sales-executive - product-management - product-management/product-development - product-management/product-management - engineering-technical - engineering-technical/artificial-intelligence-machine-learning - engineering-technical/bioengineering - engineering-technical/biometrics - engineering-technical/business-intelligence - engineering-technical/chemical-engineering - engineering-technical/cloud-mobility - engineering-technical/data-science - engineering-technical/devops - engineering-technical/digital-transformation - engineering-technical/emerging-technology-innovation - engineering-technical/engineering-technical - engineering-technical/industrial-engineering - engineering-technical/mechanic - engineering-technical/mobile-development - engineering-technical/project-management - engineering-technical/research-development - engineering-technical/scrum-master-agile-coach - engineering-technical/software-development - engineering-technical/support-technical-services - engineering-technical/technician - engineering-technical/technology-operations - engineering-technical/test-quality-assurance - engineering-technical/ui-ux - engineering-technical/web-development - design - design/all-design - design/product-ui-ux-design - design/graphic-design - education - education/teacher - education/principal - education/superintendent - education/professor - finance - finance/accounting - finance/finance - finance/financial-planning-analysis - finance/financial-reporting - finance/financial-strategy - finance/financial-systems - finance/internal-audit-control - finance/investor-relations - finance/mergers-acquisitions - finance/real-estate-finance - finance/financial-risk - finance/shared-services - finance/sourcing-procurement - finance/tax - finance/treasury - human-resources - human-resources/compensation-benefits - human-resources/culture-diversity-inclusion - human-resources/employee-labor-relations - human-resources/health-safety - human-resources/human-resource-information-system - human-resources/human-resources - human-resources/hr-business-partner - human-resources/learning-development - human-resources/organizational-development - human-resources/recruiting-talent-acquisition - human-resources/talent-management - human-resources/workforce-management - human-resources/people-operations - information-technology - information-technology/application-development - information-technology/business-service-management-itsm - information-technology/collaboration-web-app - information-technology/data-center - information-technology/data-warehouse - information-technology/database-administration - information-technology/ecommerce-development - information-technology/enterprise-architecture - information-technology/help-desk-desktop-services - information-technology/hr-financial-erp-systems - information-technology/information-security - information-technology/information-technology - information-technology/infrastructure - information-technology/it-asset-management - information-technology/it-audit-it-compliance - information-technology/it-operations - information-technology/it-procurement - information-technology/it-strategy - information-technology/it-training - information-technology/networking - information-technology/project-program-management - information-technology/quality-assurance - information-technology/retail-store-systems - information-technology/servers - information-technology/storage-disaster-recovery - information-technology/telecommunications - information-technology/virtualization - legal - legal/acquisitions - legal/compliance - legal/contracts - legal/corporate-secretary - legal/ediscovery - legal/ethics - legal/governance - legal/governmental-affairs-regulatory-law - legal/intellectual-property-patent - legal/labor-employment - legal/lawyer-attorney - legal/legal - legal/legal-counsel - legal/legal-operations - legal/litigation - legal/privacy - marketing - marketing/advertising - marketing/brand-management - marketing/content-marketing - marketing/customer-experience - marketing/customer-marketing - marketing/demand-generation - marketing/digital-marketing - marketing/ecommerce-marketing - marketing/event-marketing - marketing/field-marketing - marketing/lead-generation - marketing/marketing - marketing/marketing-analytics-insights - marketing/marketing-communications - marketing/marketing-operations - marketing/product-marketing - marketing/public-relations - marketing/search-engine-optimization-pay-per-click - marketing/social-media-marketing - marketing/strategic-communications - marketing/technical-marketing - medical-health - medical-health/anesthesiology - medical-health/chiropractics - medical-health/clinical-systems - medical-health/dentistry - medical-health/dermatology - medical-health/doctors-physicians - medical-health/epidemiology - medical-health/first-responder - medical-health/infectious-disease - medical-health/medical-administration - medical-health/medical-education-training - medical-health/medical-research - medical-health/medicine - medical-health/neurology - medical-health/nursing - medical-health/nutrition-dietetics - medical-health/obstetrics-gynecology - medical-health/oncology - medical-health/opthalmology - medical-health/optometry - medical-health/orthopedics - medical-health/pathology - medical-health/pediatrics - medical-health/pharmacy - medical-health/physical-therapy - medical-health/psychiatry - medical-health/psychology - medical-health/public-health - medical-health/radiology - medical-health/social-work - operations - operations/call-center - operations/construction - operations/corporate-strategy - operations/customer-service-support - operations/enterprise-resource-planning - operations/facilities-management - operations/leasing - operations/logistics - operations/office-operations - operations/operations - operations/physical-security - operations/project-development - operations/quality-management - operations/real-estate - operations/safety - operations/store-operations - operations/supply-chain - sales - sales/account-management - sales/business-development - sales/channel-sales - sales/customer-retention-development - sales/customer-success - sales/field-outside-sales - sales/inside-sales - sales/partnerships - sales/revenue-operations - sales/sales - sales/sales-enablement - sales/sales-engineering - sales/sales-operations - sales/sales-training - consulting - consulting/consultant - null description: The person's current department nullable: true PersonLocationResponse: type: object properties: country: $ref: '#/components/schemas/PersonCountryResponse' address: type: string description: The person's reported location nullable: true description: The person location nullable: true PersonSocialsResponse: type: object properties: linkedinUrl: type: string description: The person LinkedIn URL nullable: true description: The person social profiles PersonExperienceResponse: required: - isCurrent - isMatched type: object properties: startDate: type: string description: The date the experience started format: date nullable: true endDate: type: string description: The date the experience ended format: date nullable: true isCurrent: type: boolean description: Whether this is a current experience isMatched: type: boolean description: Whether this experience matched the search filters position: type: string description: The position or title held during the experience nullable: true seniority: $ref: '#/components/schemas/NullableOfPersonSeniority2' department: $ref: '#/components/schemas/NullableOfPersonDepartment2' company: $ref: '#/components/schemas/PersonExperienceCompanyResponse' companyName: type: string description: The reported company name when no company record was matched nullable: true PersonEducationResponse: required: - institutionName type: object properties: institutionName: type: string description: The name of the educational institution institution: $ref: '#/components/schemas/PersonCompanyResponse' socialHandle: type: string description: The social media handle of the educational institution nullable: true degree: type: array items: type: string description: The degrees or fields of study associated with this education entry nullable: true startYear: type: integer description: The year this education entry started format: int16 nullable: true endYear: type: integer description: The year this education entry ended format: int16 nullable: true PersonCountryResponse: required: - code - name type: object properties: code: type: string description: The ISO 3166-1 alpha-2 country code name: type: string description: The country name description: The country where the person is located nullable: true NullableOfPersonSeniority2: enum: - owner - founder - c-suite - partner - vp - head - director - manager - senior - entry - intern - null description: The seniority level associated with the experience nullable: true NullableOfPersonDepartment2: enum: - c-suite - c-suite/executive - c-suite/finance-executive - c-suite/founder - c-suite/human-resources-executive - c-suite/information-technology-executive - c-suite/legal-executive - c-suite/marketing-executive - c-suite/medical-health-executive - c-suite/operations-executive - c-suite/sales-executive - product-management - product-management/product-development - product-management/product-management - engineering-technical - engineering-technical/artificial-intelligence-machine-learning - engineering-technical/bioengineering - engineering-technical/biometrics - engineering-technical/business-intelligence - engineering-technical/chemical-engineering - engineering-technical/cloud-mobility - engineering-technical/data-science - engineering-technical/devops - engineering-technical/digital-transformation - engineering-technical/emerging-technology-innovation - engineering-technical/engineering-technical - engineering-technical/industrial-engineering - engineering-technical/mechanic - engineering-technical/mobile-development - engineering-technical/project-management - engineering-technical/research-development - engineering-technical/scrum-master-agile-coach - engineering-technical/software-development - engineering-technical/support-technical-services - engineering-technical/technician - engineering-technical/technology-operations - engineering-technical/test-quality-assurance - engineering-technical/ui-ux - engineering-technical/web-development - design - design/all-design - design/product-ui-ux-design - design/graphic-design - education - education/teacher - education/principal - education/superintendent - education/professor - finance - finance/accounting - finance/finance - finance/financial-planning-analysis - finance/financial-reporting - finance/financial-strategy - finance/financial-systems - finance/internal-audit-control - finance/investor-relations - finance/mergers-acquisitions - finance/real-estate-finance - finance/financial-risk - finance/shared-services - finance/sourcing-procurement - finance/tax - finance/treasury - human-resources - human-resources/compensation-benefits - human-resources/culture-diversity-inclusion - human-resources/employee-labor-relations - human-resources/health-safety - human-resources/human-resource-information-system - human-resources/human-resources - human-resources/hr-business-partner - human-resources/learning-development - human-resources/organizational-development - human-resources/recruiting-talent-acquisition - human-resources/talent-management - human-resources/workforce-management - human-resources/people-operations - information-technology - information-technology/application-development - information-technology/business-service-management-itsm - information-technology/collaboration-web-app - information-technology/data-center - information-technology/data-warehouse - information-technology/database-administration - information-technology/ecommerce-development - information-technology/enterprise-architecture - information-technology/help-desk-desktop-services - information-technology/hr-financial-erp-systems - information-technology/information-security - information-technology/information-technology - information-technology/infrastructure - information-technology/it-asset-management - information-technology/it-audit-it-compliance - information-technology/it-operations - information-technology/it-procurement - information-technology/it-strategy - information-technology/it-training - information-technology/networking - information-technology/project-program-management - information-technology/quality-assurance - information-technology/retail-store-systems - information-technology/servers - information-technology/storage-disaster-recovery - information-technology/telecommunications - information-technology/virtualization - legal - legal/acquisitions - legal/compliance - legal/contracts - legal/corporate-secretary - legal/ediscovery - legal/ethics - legal/governance - legal/governmental-affairs-regulatory-law - legal/intellectual-property-patent - legal/labor-employment - legal/lawyer-attorney - legal/legal - legal/legal-counsel - legal/legal-operations - legal/litigation - legal/privacy - marketing - marketing/advertising - marketing/brand-management - marketing/content-marketing - marketing/customer-experience - marketing/customer-marketing - marketing/demand-generation - marketing/digital-marketing - marketing/ecommerce-marketing - marketing/event-marketing - marketing/field-marketing - marketing/lead-generation - marketing/marketing - marketing/marketing-analytics-insights - marketing/marketing-communications - marketing/marketing-operations - marketing/product-marketing - marketing/public-relations - marketing/search-engine-optimization-pay-per-click - marketing/social-media-marketing - marketing/strategic-communications - marketing/technical-marketing - medical-health - medical-health/anesthesiology - medical-health/chiropractics - medical-health/clinical-systems - medical-health/dentistry - medical-health/dermatology - medical-health/doctors-physicians - medical-health/epidemiology - medical-health/first-responder - medical-health/infectious-disease - medical-health/medical-administration - medical-health/medical-education-training - medical-health/medical-research - medical-health/medicine - medical-health/neurology - medical-health/nursing - medical-health/nutrition-dietetics - medical-health/obstetrics-gynecology - medical-health/oncology - medical-health/opthalmology - medical-health/optometry - medical-health/orthopedics - medical-health/pathology - medical-health/pediatrics - medical-health/pharmacy - medical-health/physical-therapy - medical-health/psychiatry - medical-health/psychology - medical-health/public-health - medical-health/radiology - medical-health/social-work - operations - operations/call-center - operations/construction - operations/corporate-strategy - operations/customer-service-support - operations/enterprise-resource-planning - operations/facilities-management - operations/leasing - operations/logistics - operations/office-operations - operations/operations - operations/physical-security - operations/project-development - operations/quality-management - operations/real-estate - operations/safety - operations/store-operations - operations/supply-chain - sales - sales/account-management - sales/business-development - sales/channel-sales - sales/customer-retention-development - sales/customer-success - sales/field-outside-sales - sales/inside-sales - sales/partnerships - sales/revenue-operations - sales/sales - sales/sales-enablement - sales/sales-engineering - sales/sales-operations - sales/sales-training - consulting - consulting/consultant - null description: The department associated with the experience nullable: true PersonExperienceCompanyResponse: required: - id type: object properties: legalName: type: string description: The legal name of the company nullable: true website: type: string description: The company website URL nullable: true description: type: string description: The company description nullable: true type: $ref: '#/components/schemas/NullableOfCompanyType' foundedYear: type: integer description: The year the company was founded format: int32 nullable: true employees: $ref: '#/components/schemas/NullableOfCompanyEmployees' revenue: $ref: '#/components/schemas/NullableOfCompanyRevenue' industries: type: array items: type: string description: The industries associated with the company nullable: true categories: type: array items: $ref: '#/components/schemas/CompanyCategory' description: >- The categories associated with the company, from most to least specific nullable: true location: $ref: '#/components/schemas/CompanyLocationResponse' socials: $ref: '#/components/schemas/CompanySocialsResponse' updatedAt: type: string description: When the company data was last updated format: date-time nullable: true id: type: string description: The CompanyEnrich ID of the company format: uuid name: type: string description: The company name nullable: true domain: type: string description: The primary company domain nullable: true logoUrl: type: string description: The company logo URL nullable: true industry: type: string description: The company's primary industry nullable: true description: >- The matched company associated with the experience. Includes the standard company profile when `company` is requested in `expand` and the company is available. nullable: true PersonCompanyResponse: required: - id type: object properties: id: type: string description: The CompanyEnrich ID of the company format: uuid name: type: string description: The company name nullable: true domain: type: string description: The primary company domain nullable: true logoUrl: type: string description: The company logo URL nullable: true industry: type: string description: The company's primary industry nullable: true description: The matched educational institution nullable: true NullableOfCompanyType: enum: - private - public - self-employed - self-owned - partnership - nonprofit - educational - government - null description: The company type nullable: true NullableOfCompanyEmployees: enum: - 1-10 - 11-50 - 51-200 - 201-500 - 501-1K - 1K-5K - 5K-10K - over-10K - null description: The estimated employee count range nullable: true NullableOfCompanyRevenue: enum: - under-1m - 1m-10m - 10m-50m - 50m-100m - 100m-200m - 200m-1b - over-1b - null description: The estimated annual revenue range in USD nullable: true CompanyCategory: enum: - b2b - b2c - b2g - e-commerce - media - service-provider - mobile - saas - local-business CompanyLocationResponse: type: object properties: country: $ref: '#/components/schemas/CompanyCountryResponse' state: $ref: '#/components/schemas/CompanyStateResponse' city: $ref: '#/components/schemas/CompanyCityResponse' address: type: string description: The company street address nullable: true postalCode: type: string description: The company postal code nullable: true phone: type: string description: The company phone number nullable: true description: The company location and contact details nullable: true CompanySocialsResponse: type: object properties: linkedinUrl: type: string description: The company LinkedIn URL nullable: true linkedinId: type: string description: The company LinkedIn ID nullable: true twitterUrl: type: string description: The company Twitter/X URL nullable: true facebookUrl: type: string description: The company Facebook URL nullable: true instagramUrl: type: string description: The company Instagram URL nullable: true angellistUrl: type: string description: The company AngelList URL nullable: true crunchbaseUrl: type: string description: The company Crunchbase URL nullable: true youtubeUrl: type: string description: The company YouTube URL nullable: true githubUrl: type: string description: The company GitHub URL nullable: true g2Url: type: string description: The company G2 URL nullable: true description: The company social profiles nullable: true CompanyCountryResponse: required: - code - name type: object properties: code: type: string description: The ISO 3166-1 alpha-2 country code name: type: string description: The country name description: The country where the company is located nullable: true CompanyStateResponse: required: - id - name type: object properties: id: type: integer description: The CompanyEnrich state ID format: int32 name: type: string description: The state or province name code: type: string description: The ISO 3166-2 subdivision code nullable: true description: The state or province where the company is located nullable: true CompanyCityResponse: required: - id - name type: object properties: id: type: integer description: The CompanyEnrich city ID format: int32 name: type: string description: The city name description: The city where the company is located nullable: true securitySchemes: Bearer: type: apiKey description: >- API Token used for authentication. Example: "Authorization: Bearer {token}" name: Authorization in: header x-bearer-format: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.