# Forager public API Forager public API endpoints documentation Version: 1.0.0 ## Servers ``` https://api-v2.forager.ai ``` ## Security ### Api-Key Type: apiKey In: header Name: X-API-KEY ## Download OpenAPI description [Forager public API](https://docs.forager.ai/_bundle/openapi.yaml) ## Job Posts Search the Forager job-post index. Use these endpoints to find job postings by attributes such as title, location, posted date, or hiring organization, and to retrieve aggregate totals for a given query before paginating through full results. ### Job post event search - [POST /api/{account_id}/datastorage/job_search/](https://docs.forager.ai/openapi/job-posts/datastorage_job_search_create.md): Job post event search. ### Job post event search totals - [POST /api/{account_id}/datastorage/job_search/totals/](https://docs.forager.ai/openapi/job-posts/datastorage_job_search_totals_create.md): Job post event search totals. ## Organizations Search the Forager organization index. Filter companies by attributes such as industry, headcount, location, keywords, and web technologies, and retrieve total match counts alongside the result set. ### Organization search - [POST /api/{account_id}/datastorage/organization_search/](https://docs.forager.ai/openapi/organizations/datastorage_organization_search_create.md): Organization search. ### Organization search totals - [POST /api/{account_id}/datastorage/organization_search/totals/](https://docs.forager.ai/openapi/organizations/datastorage_organization_search_totals_create.md): Organization search totals. ## People Look up people and their contact data. Use the search endpoints to find people by role, employer, location, or skills; use the detail-lookup endpoints to fetch a full person record by ID, email, or phone number; and use the contacts-lookup endpoints to retrieve work emails, personal emails, or phone numbers for a known person. ### Personal emails lookup - [POST /api/{account_id}/datastorage/person_contacts_lookup/personal_emails/](https://docs.forager.ai/openapi/people/datastorage_person_contacts_lookup_personal_emails_create.md): The Person Personal Emails Lookup endpoint retrieves personal email addresses associated with an individual in the Forager dataset. It allows you to input identifying information (such as Linkedin handle or Forager ID) and returns available personal contact emails. Personal emails may include both free webmail addresses (e.g., Gmail, Yahoo) and custom domains that look like company domains but are used for personal purposes. For example, if a user registers for services like LinkedIn with a custom domain for personal use, that email will appear in personal searches. ### Phone numbers lookup - [POST /api/{account_id}/datastorage/person_contacts_lookup/phone_numbers/](https://docs.forager.ai/openapi/people/datastorage_person_contacts_lookup_phone_numbers_create.md): The Person Phone Numbers Lookup endpoint retrieves phone numbers associated with an individual in the Forager dataset. It allows you to input identifying information (such as Linkedin handle or Forager ID) and returns available phone numbers. This API is useful for enriching person records, supporting lead generation, and verifying phone contact details within your applications. ### Work emails lookup - [POST /api/{account_id}/datastorage/person_contacts_lookup/work_emails/](https://docs.forager.ai/openapi/people/datastorage_person_contacts_lookup_work_emails_create.md): The Person Work Emails Lookup endpoint retrieves work email addresses associated with an individual in the Forager dataset. It allows you to input identifying information (such as Linkedin handle or Forager ID) and returns available work email addresses. This API is useful for enriching person records, supporting lead generation, and verifying work contact details within your applications. ### Person detail lookup - [POST /api/{account_id}/datastorage/person_detail_lookup/](https://docs.forager.ai/openapi/people/datastorage_person_detail_lookup_create.md): Do Person details lookup. ### Person detail lookup by email - [POST /api/{account_id}/datastorage/person_detail_reverse_lookup/by_email/](https://docs.forager.ai/openapi/people/datastorage_person_detail_reverse_lookup_by_email_create.md): Do reverse lookup of person details by email. ### Person detail lookup by phone - [POST /api/{account_id}/datastorage/person_detail_reverse_lookup/by_phone_number/](https://docs.forager.ai/openapi/people/datastorage_person_detail_reverse_lookup_by_phone_number_create.md): Do reverse lookup of person details by phone number. ### Person role search - [POST /api/{account_id}/datastorage/person_role_search/](https://docs.forager.ai/openapi/people/datastorage_person_role_search_create.md): The Person Role Search endpoint lets you search for individuals based on their roles, titles, time periods, and associated organizations. You can filter by attributes like role title or description, current status, start/end dates, person name, skills, industry, and location. The response returns matching person records along with their role history and linked organization details (e.g. name, domain, founding date). ### Person role search totals - [POST /api/{account_id}/datastorage/person_role_search/totals/](https://docs.forager.ai/openapi/people/datastorage_person_role_search_totals_create.md): Organization person role search totals. ## Websites Look up information about a website, including the organization that owns it and the technologies detected on the domain. ### Website Details Lookup - [POST /api/{account_id}/datastorage/website_detail_lookup/](https://docs.forager.ai/openapi/websites/datastorage_website_detail_lookup_create.md): The Website Details Lookup endpoint retrieves detailed information about a specific website, including its domain, web rank, traffic, and associated web technologies. This API is useful for analyzing website performance, understanding technology stack, and integrating website data into your applications. ## Users Manage your Forager account. Retrieve the current authenticated user, create and revoke API keys used to authenticate requests to the rest of the API, and review the credit balance-change log that records every lookup charge or adjustment against your account. ### Credit Balance Change Log - [GET /api/{account_id}/subscriptions/balance_change_logs/](https://docs.forager.ai/openapi/users/subscriptions_balance_change_logs_list.md): The Credit Balance Change Log endpoint provides a list of all credit balance change logs related to the current subscription. It returns a list of credit balance change logs, including the change type, change sum, and change data. This endpoint is useful for tracking and analyzing credit consumption patterns, monitoring usage, and ensuring proper subscription management. ### Credit Consumption Totals - [GET /api/{account_id}/subscriptions/balance_change_logs/totals/](https://docs.forager.ai/openapi/users/subscriptions_balance_change_logs_totals_retrieve.md): The Credit Consumption Totals endpoint calculates the total amount of credits spent during a specified timeframe. It returns the sum of all credit changes that have been made to the subscription balance during the given period. This endpoint is useful for tracking and analyzing credit consumption patterns, monitoring usage, and ensuring proper subscription management. ### List API keys - [GET /api/api_keys/](https://docs.forager.ai/openapi/users/api_keys_list.md): API view for managing API keys. ### Create a new API key - [POST /api/api_keys/](https://docs.forager.ai/openapi/users/api_keys_create.md): Handle creation of a new API key. ### View API key details - [GET /api/api_keys/{prefix}/](https://docs.forager.ai/openapi/users/api_keys_retrieve.md): API view for managing API keys. ### Delete API key - [DELETE /api/api_keys/{prefix}/](https://docs.forager.ai/openapi/users/api_keys_destroy.md): API view for managing API keys. ### View user information - [GET /api/users/current/](https://docs.forager.ai/openapi/users/users_current_retrieve.md): A view to retrieve current user details. ## Autocomplete Resolve free-text input into the canonical IDs used elsewhere in the API. Each endpoint returns matching options for a search term (industries, organizations, organization keywords, locations, person skills, web technologies) so they can be passed as filters to the search endpoints. ### Industries lookup - [GET /api/datastorage/autocomplete/industries/](https://docs.forager.ai/openapi/autocomplete/v1_industry_lookup.md): Industries objects lookup. ### Organizations lookup - [GET /api/datastorage/autocomplete/organizations/](https://docs.forager.ai/openapi/autocomplete/v1_organization_lookup.md): Organizations objects lookup. ### Organization keywords lookup - [GET /api/datastorage/autocomplete/organization_keywords/](https://docs.forager.ai/openapi/autocomplete/v1_organization_keyword_lookup.md): Organization keywords objects lookup. ### Locations lookup - [GET /api/datastorage/autocomplete/locations/](https://docs.forager.ai/openapi/autocomplete/v1_location_lookup.md): Locations objects lookup. ### Person skills lookup - [GET /api/datastorage/autocomplete/person_skills/](https://docs.forager.ai/openapi/autocomplete/v1_person_skill_lookup.md): Person skills objects lookup. ### Web technologies lookup - [GET /api/datastorage/autocomplete/web_technologies/](https://docs.forager.ai/openapi/autocomplete/v1_web_technology_lookup.md): Web technologies objects lookup. ## Feedback Report verification feedback for contact data (phone numbers, personal emails, work emails) returned by Forager person lookups. Use these endpoints to submit whether a contact value is valid/invalid and whether it belongs to the matched person — every submission is stored as a new row and is used to improve the accuracy of future lookups. ### Submit personal-email verification feedback - [POST /api/{account_id}/datastorage/feedback/personal_emails/](https://docs.forager.ai/openapi/feedback/datastorage_feedback_personal_emails_create.md): Submit verification feedback for a personal email address returned by a Forager person lookup. Required fields: email (lowercased and stripped before storage), contact_status (one of valid or invalid), and is_correct_person (boolean). Optional: name (the person's name the email belongs to, e.g. John Doe) and person_id. Every submission creates a new row with 201 Created. ### Submit phone-number verification feedback - [POST /api/{account_id}/datastorage/feedback/phone_numbers/](https://docs.forager.ai/openapi/feedback/datastorage_feedback_phone_numbers_create.md): Submit verification feedback for a phone number returned by a Forager person lookup. Required fields: phone_number (any format; it is normalised to E.164 before storage), contact_status (one of connected or disconnected, reflecting the live-call outcome), and is_correct_person (boolean — did the call confirm the number belongs to the matched person). Optional: name (the person's name the caller believes the number belongs to, e.g. John Doe) and person_id (associate the row with a specific Forager person ID). Every submission creates a new row with 201 Created; repeat submissions for the same contact are preserved as separate rows. ### Submit work-email verification feedback - [POST /api/{account_id}/datastorage/feedback/work_emails/](https://docs.forager.ai/openapi/feedback/datastorage_feedback_work_emails_create.md): Submit verification feedback for a work email address returned by a Forager person lookup. Required fields: email, contact_status (one of valid or invalid), and is_correct_person. Optional: name and person_id. Reports for the same address via both the work and personal endpoints store two distinct rows distinguished by email type.