openapi: 3.0.3 info: title: Forager public API version: 1.0.0 description: Forager public API endpoints documentation paths: /api/{account_id}/datastorage/feedback/personal_emails/: post: operationId: datastorage_feedback_personal_emails_create description: >- Submit verification feedback for a personal email address returned by a Forager person lookup. Required fields: `email` (lowercased and stripped before storage) and `contact_status` (one of `valid` or `invalid`). Optional: `is_correct_person` (boolean) — omit it, or send `null`, when the exchange never revealed whose address it is; an `invalid` address bounces before anyone can confirm a name. Omitted and `null` are both stored and returned as `null`, meaning "unknown", which is deliberately distinct from `false` ("this is the wrong person"). Also 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`. summary: Submit personal-email verification feedback parameters: - in: path name: account_id schema: type: integer required: true tags: - Feedback requestBody: content: application/json: schema: $ref: '#/components/schemas/EmailFeedbackRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/EmailFeedbackRequest' multipart/form-data: schema: $ref: '#/components/schemas/EmailFeedbackRequest' required: true security: - Api-Key: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/EmailFeedbackResponse' description: '' '400': description: >- Validation failed. The body contained an invalid contact value (e.g. a phone number that cannot be parsed as E.164, or a malformed email address), an unrecognised `contact_status` value, or a missing required field. '403': description: >- Authentication failed. The request was missing a valid `X-API-Key` header, the key was for a different account, or the API key user is inactive. '429': description: >- Rate limit exceeded. Feedback endpoints share a per-account budget of 60 requests per minute. /api/{account_id}/datastorage/feedback/phone_numbers/: post: operationId: datastorage_feedback_phone_numbers_create description: >- 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) and `contact_status` (one of `connected` or `disconnected`, reflecting the live-call outcome). Optional: `is_correct_person` (boolean — did the call confirm the number belongs to the matched person). Omit it, or send `null`, when the call could not answer that question — a `disconnected` number never reaches anyone, so there is nobody to identify. Omitted and `null` are both stored and returned as `null`, meaning "unknown", which is deliberately distinct from `false` ("this is the wrong person"). Also 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. summary: Submit phone-number verification feedback parameters: - in: path name: account_id schema: type: integer required: true tags: - Feedback requestBody: content: application/json: schema: $ref: '#/components/schemas/PhoneFeedbackRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PhoneFeedbackRequest' multipart/form-data: schema: $ref: '#/components/schemas/PhoneFeedbackRequest' required: true security: - Api-Key: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/PhoneFeedbackResponse' description: '' '400': description: >- Validation failed. The body contained an invalid contact value (e.g. a phone number that cannot be parsed as E.164, or a malformed email address), an unrecognised `contact_status` value, or a missing required field. '403': description: >- Authentication failed. The request was missing a valid `X-API-Key` header, the key was for a different account, or the API key user is inactive. '429': description: >- Rate limit exceeded. Feedback endpoints share a per-account budget of 60 requests per minute. /api/{account_id}/datastorage/feedback/work_emails/: post: operationId: datastorage_feedback_work_emails_create description: >- Submit verification feedback for a work email address returned by a Forager person lookup. Required fields: `email` and `contact_status` (one of `valid` or `invalid`). Optional: `is_correct_person` — omit it, or send `null`, when the exchange never revealed whose address it is; `null` means "unknown" and is deliberately distinct from `false` ("this is the wrong person"). Also 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. summary: Submit work-email verification feedback parameters: - in: path name: account_id schema: type: integer required: true tags: - Feedback requestBody: content: application/json: schema: $ref: '#/components/schemas/EmailFeedbackRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/EmailFeedbackRequest' multipart/form-data: schema: $ref: '#/components/schemas/EmailFeedbackRequest' required: true security: - Api-Key: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/EmailFeedbackResponse' description: '' '400': description: >- Validation failed. The body contained an invalid contact value (e.g. a phone number that cannot be parsed as E.164, or a malformed email address), an unrecognised `contact_status` value, or a missing required field. '403': description: >- Authentication failed. The request was missing a valid `X-API-Key` header, the key was for a different account, or the API key user is inactive. '429': description: >- Rate limit exceeded. Feedback endpoints share a per-account budget of 60 requests per minute. /api/{account_id}/datastorage/job_search/: post: operationId: datastorage_job_search_create description: Job post event search. summary: Job post event search parameters: - in: path name: account_id schema: type: integer required: true tags: - Job Posts requestBody: content: application/json: schema: $ref: '#/components/schemas/JobPostEventSearch' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/JobPostEventSearch' multipart/form-data: schema: $ref: '#/components/schemas/JobPostEventSearch' security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: $ref: '#/components/schemas/JobPostEventSearchResponse' description: '' /api/{account_id}/datastorage/job_search/totals/: post: operationId: datastorage_job_search_totals_create description: Job post event search totals. summary: Job post event search totals parameters: - in: path name: account_id schema: type: integer required: true tags: - Job Posts requestBody: content: application/json: schema: $ref: '#/components/schemas/JobPostEventSearch' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/JobPostEventSearch' multipart/form-data: schema: $ref: '#/components/schemas/JobPostEventSearch' security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: $ref: '#/components/schemas/JobPostEventSearchTotalsResponse' description: '' /api/{account_id}/datastorage/organization_search/: post: operationId: datastorage_organization_search_create description: Organization search. summary: Organization search parameters: - in: path name: account_id schema: type: integer required: true tags: - Organizations requestBody: content: application/json: schema: $ref: '#/components/schemas/OrganizationSearchRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/OrganizationSearchRequest' multipart/form-data: schema: $ref: '#/components/schemas/OrganizationSearchRequest' security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: $ref: '#/components/schemas/OrganizationSearchResponse' description: '' /api/{account_id}/datastorage/organization_search/totals/: post: operationId: datastorage_organization_search_totals_create description: Organization search totals. summary: Organization search totals parameters: - in: path name: account_id schema: type: integer required: true tags: - Organizations requestBody: content: application/json: schema: $ref: '#/components/schemas/OrganizationSearchRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/OrganizationSearchRequest' multipart/form-data: schema: $ref: '#/components/schemas/OrganizationSearchRequest' security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: $ref: '#/components/schemas/OrganizationSearchTotalsResponse' description: '' /api/{account_id}/datastorage/person_contacts_lookup/personal_emails/: post: operationId: datastorage_person_contacts_lookup_personal_emails_create description: >- 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. The endpoint returns only addresses on free webmail / consumer providers (Gmail, Outlook, Yahoo, iCloud, Proton, and similar). Addresses on corporate domains, educational domains (e.g., .edu, .ac.uk), and any other custom domains are excluded — including custom domains a person uses for personal purposes — to keep deliverability of the returned set high. If the filtered set is empty, the endpoint returns 200 OK with an empty body and does not consume credits. summary: Personal emails lookup parameters: - in: path name: account_id schema: type: integer required: true tags: - Personal Emails requestBody: content: application/json: schema: $ref: '#/components/schemas/PersonInfoRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PersonInfoRequest' multipart/form-data: schema: $ref: '#/components/schemas/PersonInfoRequest' security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/PersonEmailDetail' description: '' /api/{account_id}/datastorage/person_contacts_lookup/phone_numbers/: post: operationId: datastorage_person_contacts_lookup_phone_numbers_create description: >- 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. summary: Phone numbers lookup parameters: - in: path name: account_id schema: type: integer required: true tags: - Phones requestBody: content: application/json: schema: $ref: '#/components/schemas/PersonInfoRequest' examples: By Forager ID: value: person_id: 123 By LinkedIn public identifier: value: linkedin_public_identifier: billgates application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PersonInfoRequest' multipart/form-data: schema: $ref: '#/components/schemas/PersonInfoRequest' security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/PersonPhoneDetail' description: '' /api/{account_id}/datastorage/person_detail_lookup/: post: operationId: datastorage_person_detail_lookup_create description: Do Person details lookup. summary: Person detail lookup parameters: - in: path name: account_id schema: type: integer required: true tags: - People requestBody: content: application/json: schema: $ref: '#/components/schemas/PersonInfoRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PersonInfoRequest' multipart/form-data: schema: $ref: '#/components/schemas/PersonInfoRequest' security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: $ref: '#/components/schemas/PersonDetail' description: '' /api/{account_id}/datastorage/person_detail_reverse_lookup/by_email/: post: operationId: datastorage_person_detail_reverse_lookup_by_email_create description: Do reverse lookup of person details by email. summary: Person detail lookup by email parameters: - in: path name: account_id schema: type: integer required: true tags: - People requestBody: content: application/json: schema: $ref: '#/components/schemas/PersonReverseSearchByEmail' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PersonReverseSearchByEmail' multipart/form-data: schema: $ref: '#/components/schemas/PersonReverseSearchByEmail' required: true security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: $ref: '#/components/schemas/PersonDetail' description: '' /api/{account_id}/datastorage/person_detail_reverse_lookup/by_phone_number/: post: operationId: datastorage_person_detail_reverse_lookup_by_phone_number_create description: Do reverse lookup of person details by phone number. summary: Person detail lookup by phone parameters: - in: path name: account_id schema: type: integer required: true tags: - People requestBody: content: application/json: schema: $ref: '#/components/schemas/PersonReverseSearchByPhoneNumber' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PersonReverseSearchByPhoneNumber' multipart/form-data: schema: $ref: '#/components/schemas/PersonReverseSearchByPhoneNumber' required: true security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: $ref: '#/components/schemas/PersonDetail' description: '' /api/{account_id}/datastorage/person_role_search/: post: operationId: datastorage_person_role_search_create description: >- 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). summary: Person role search parameters: - in: path name: account_id schema: type: integer required: true tags: - People requestBody: content: application/json: schema: $ref: '#/components/schemas/OrganizationPersonRoleSearch' examples: Current Software Engineers: value: role_title: Software Engineer role_is_current: true application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/OrganizationPersonRoleSearch' multipart/form-data: schema: $ref: '#/components/schemas/OrganizationPersonRoleSearch' security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: $ref: '#/components/schemas/PersonRoleSearchResponse' description: '' /api/{account_id}/datastorage/person_role_search/totals/: post: operationId: datastorage_person_role_search_totals_create description: Organization person role search totals. summary: Person role search totals parameters: - in: path name: account_id schema: type: integer required: true tags: - People requestBody: content: application/json: schema: $ref: '#/components/schemas/OrganizationPersonRoleSearch' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/OrganizationPersonRoleSearch' multipart/form-data: schema: $ref: '#/components/schemas/OrganizationPersonRoleSearch' security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: $ref: '#/components/schemas/PersonRoleSearchTotalsResponse' description: '' /api/{account_id}/datastorage/website_detail_lookup/: post: operationId: datastorage_website_detail_lookup_create description: >- 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. summary: Website Details Lookup parameters: - in: path name: account_id schema: type: integer required: true tags: - Websites requestBody: content: application/json: schema: $ref: '#/components/schemas/WebSiteLookupRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/WebSiteLookupRequest' multipart/form-data: schema: $ref: '#/components/schemas/WebSiteLookupRequest' security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: $ref: '#/components/schemas/WebSite' description: '' /api/{account_id}/subscriptions/balance_change_logs/: get: operationId: subscriptions_balance_change_logs_list description: >- 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. summary: Credit Balance Change Log parameters: - in: path name: account_id schema: type: integer required: true - in: query name: date_created_end schema: type: string format: date-time - in: query name: date_created_start schema: type: string format: date-time - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer tags: - Users security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedCreditsBalanceChangeLogList' description: '' /api/{account_id}/subscriptions/balance_change_logs/totals/: get: operationId: subscriptions_balance_change_logs_totals_retrieve description: >- 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. summary: Credit Consumption Totals parameters: - in: path name: account_id schema: type: integer required: true - in: query name: date_created_end schema: type: string format: date-time - in: query name: date_created_start schema: type: string format: date-time tags: - Users security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: $ref: '#/components/schemas/TotalCreditsSpent' description: '' /api/api_keys/: get: operationId: api_keys_list description: API view for managing API keys. summary: List API keys tags: - Users security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/APIKey' description: '' post: operationId: api_keys_create description: Handle creation of a new API key. summary: Create a new API key tags: - Users requestBody: content: application/json: schema: $ref: '#/components/schemas/APIKey' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/APIKey' multipart/form-data: schema: $ref: '#/components/schemas/APIKey' security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '201': content: application/json: schema: $ref: '#/components/schemas/APIKey' description: '' /api/api_keys/{prefix}/: get: operationId: api_keys_retrieve description: API view for managing API keys. summary: View API key details parameters: - in: path name: prefix schema: type: string required: true tags: - Users security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: $ref: '#/components/schemas/APIKey' description: '' delete: operationId: api_keys_destroy description: API view for managing API keys. summary: Delete API key parameters: - in: path name: prefix schema: type: string required: true tags: - Users security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '204': description: No response body /api/users/current/: get: operationId: users_current_retrieve description: A view to retrieve current user details. summary: View user information tags: - Users security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: $ref: '#/components/schemas/User' description: '' /api/v2/{account_id}/datastorage/person_contacts_lookup/work_emails/: post: operationId: v2_datastorage_person_contacts_lookup_work_emails_create description: >- Start a work email lookup and return immediately with a job id. Identify the person either by `first_name`, `last_name` and `domain`, or by `linkedin_public_identifier`, in which case the name and the domain of their current employer are taken from the Forager dataset. The lookup itself runs asynchronously because proving an address is deliverable takes longer than a request should wait: poll the returned `status_check_url` until `status` is `completed` or `failed`. Credits are charged once, only when an address is found, and polling is always free. This endpoint is rate limited for interactive use - for enrichment runs use the bulk endpoint, which is both faster and cheaper for us to serve. summary: Single work email lookup parameters: - in: path name: account_id schema: type: integer required: true tags: - Work Emails requestBody: content: application/json: schema: $ref: '#/components/schemas/WorkEmailLookupSubmitRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/WorkEmailLookupSubmitRequest' multipart/form-data: schema: $ref: '#/components/schemas/WorkEmailLookupSubmitRequest' security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '202': content: application/json: schema: $ref: '#/components/schemas/WorkEmailLookupSubmitted' description: '' /api/v2/{account_id}/datastorage/person_contacts_lookup/work_emails/{job_id}/: get: operationId: v2_datastorage_person_contacts_lookup_work_emails_retrieve description: >- Return the current state of a work email lookup. `status` describes the job (`queued`, `running`, `awaiting_provider`, `completed`, `failed`) and `result` describes the outcome once it is terminal (`found` or `not_found`). While the job is not terminal a `Retry-After` header suggests when to poll again. Polling never consumes credits. summary: Single work email lookup result parameters: - in: path name: account_id schema: type: integer required: true - in: path name: job_id schema: type: string format: uuid required: true tags: - Work Emails security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: $ref: '#/components/schemas/WorkEmailLookupJob' description: '' /api/v2/{account_id}/datastorage/person_contacts_lookup/work_emails/bulk/: post: operationId: v2_datastorage_person_contacts_lookup_work_emails_bulk_create description: >- Submit many work email lookups in one request. Items already answered by our cache are resolved immediately at no vendor cost and reported as `resolved_from_cache`; duplicates within the request collapse into a single lookup. Your credit balance must cover the whole batch, otherwise the batch is rejected and nothing is charged. Poll the batch for progress and its items endpoint for per-lookup results. summary: Bulk work email lookup parameters: - in: path name: account_id schema: type: integer required: true tags: - Work Emails requestBody: content: application/json: schema: $ref: '#/components/schemas/WorkEmailBulkRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/WorkEmailBulkRequest' multipart/form-data: schema: $ref: '#/components/schemas/WorkEmailBulkRequest' required: true security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '202': content: application/json: schema: $ref: '#/components/schemas/WorkEmailBatchSubmitted' description: '' /api/v2/{account_id}/datastorage/person_contacts_lookup/work_emails/bulk/{batch_id}/: get: operationId: v2_datastorage_person_contacts_lookup_work_emails_bulk_retrieve description: >- Return a bulk work email lookup batch. Poll until `status` is `completed`, at which point `results` holds one result per submitted lookup, in the order they were submitted, each with the same shape as a single lookup result. `results` is empty until then, so a partial answer is never mistaken for a whole one. summary: Bulk work email lookup status and results parameters: - in: path name: account_id schema: type: integer required: true - in: path name: batch_id schema: type: string format: uuid required: true tags: - Work Emails security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': content: application/json: schema: $ref: '#/components/schemas/WorkEmailBatch' description: '' /api/{account_id}/datastorage/autocomplete/industries/: get: summary: Industries lookup operationId: v1_industry_lookup tags: - Autocomplete description: Industries objects lookup. parameters: - name: account_id in: path required: true description: Account ID. Autocomplete requests are scoped to this account. schema: type: integer - name: q in: query description: Industry name. required: true schema: type: string - name: page in: query required: false schema: type: integer security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': description: Valid response. content: application/json: schema: type: object properties: results: type: array items: type: object properties: id: type: string description: Object primary key. text: type: string description: Industry name. pagination: type: object properties: more: type: boolean description: If True then the next page is available. '429': description: >- Rate limit exceeded. Autocomplete endpoints are throttled to 10 requests per second per account. /api/{account_id}/datastorage/autocomplete/organizations/: get: summary: Organizations lookup operationId: v1_organization_lookup tags: - Autocomplete description: Organizations objects lookup. parameters: - name: account_id in: path required: true description: Account ID. Autocomplete requests are scoped to this account. schema: type: integer - name: q in: query description: Organization name or domain. required: true schema: type: string - name: page in: query required: false schema: type: integer security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': description: Valid response. content: application/json: schema: type: object properties: results: type: array items: type: object properties: id: type: string description: Object primary key. text: type: string description: Organization name - Organization domain. pagination: type: object properties: more: type: boolean description: If True then the next page is available. '429': description: >- Rate limit exceeded. Autocomplete endpoints are throttled to 10 requests per second per account. /api/{account_id}/datastorage/autocomplete/organization_keywords/: get: summary: Organization keywords lookup operationId: v1_organization_keyword_lookup tags: - Autocomplete description: >- Organization keywords objects lookup. parameters: - name: account_id in: path required: true description: Account ID. Autocomplete requests are scoped to this account. schema: type: integer - name: q in: query description: Organization keyword name. required: true schema: type: string - name: page in: query required: false schema: type: integer security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': description: Valid response. content: application/json: schema: type: object properties: results: type: array items: type: object properties: id: type: string description: Object primary key. text: type: string description: Organization keywords name. pagination: type: object properties: more: type: boolean description: If True then the next page is available. '429': description: >- Rate limit exceeded. Autocomplete endpoints are throttled to 10 requests per second per account. /api/{account_id}/datastorage/autocomplete/locations/: get: summary: Locations lookup operationId: v1_location_lookup tags: - Autocomplete description: Locations objects lookup. parameters: - name: account_id in: path required: true description: Account ID. Autocomplete requests are scoped to this account. schema: type: integer - name: q in: query description: City, State, Country or Continent. required: true schema: type: string - name: page in: query required: false schema: type: integer security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': description: Valid response. content: application/json: schema: type: object properties: results: type: array items: type: object properties: id: type: string description: Object primary key. text: type: string description: Location name (Location place type). pagination: type: object properties: more: type: boolean description: If True then the next page is available. '429': description: >- Rate limit exceeded. Autocomplete endpoints are throttled to 10 requests per second per account. /api/{account_id}/datastorage/autocomplete/person_skills/: get: summary: Person skills lookup operationId: v1_person_skill_lookup tags: - Autocomplete description: Person skills objects lookup. parameters: - name: account_id in: path required: true description: Account ID. Autocomplete requests are scoped to this account. schema: type: integer - name: q in: query description: Person skill name. required: true schema: type: string - name: page in: query required: false schema: type: integer security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': description: Valid response. content: application/json: schema: type: object properties: results: type: array items: type: object properties: id: type: string description: Object primary key. text: type: string description: Person skill name. pagination: type: object properties: more: type: boolean description: If True then the next page is available. '429': description: >- Rate limit exceeded. Autocomplete endpoints are throttled to 10 requests per second per account. /api/{account_id}/datastorage/autocomplete/web_technologies/: get: summary: Web technologies lookup operationId: v1_web_technology_lookup tags: - Autocomplete description: >- Web technologies objects lookup. parameters: - name: account_id in: path required: true description: Account ID. Autocomplete requests are scoped to this account. schema: type: integer - name: q in: query description: Web technology name. required: true schema: type: string - name: page in: query required: false schema: type: integer security: - Api-Key: [] responses: '403': $ref: '#/components/responses/AuthenticationFailed' '200': description: Valid response. content: application/json: schema: type: object properties: results: type: array items: type: object properties: id: type: string description: Object primary key. text: type: string description: Web technology name. pagination: type: object properties: more: type: boolean description: If True then the next page is available. '429': description: >- Rate limit exceeded. Autocomplete endpoints are throttled to 10 requests per second per account. components: responses: AuthenticationFailed: description: >- The X-API-KEY header is missing, the key is not valid, or the key does not have permission for this resource. content: application/json: schema: type: object properties: detail: type: string example: detail: Authentication credentials were not provided. schemas: APIKey: type: object description: Declares JSON representation of `UserAPIKey` model instances. properties: prefix: type: string readOnly: true created: type: string format: date-time readOnly: true name: type: string description: >- A free-form name for the API key. Need not be unique. 50 characters max. maxLength: 50 required: - created - prefix Account: type: object description: Account serializer. properties: id: type: integer readOnly: true name: type: string maxLength: 255 subscription: allOf: - $ref: '#/components/schemas/Subscription' readOnly: true required: - id - name - subscription BillingCycleEnum: enum: - month - year type: string description: |- * `month` - Month * `year` - Year CreditsBalanceChangeLog: type: object description: >- Declares JSON representation of `CreditsBalanceChangeLog` model instances. properties: id: type: integer readOnly: true change_type: type: string change_sum: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,2})?$ title: Credits sum change_description: type: string description: Credits balance change description. readOnly: true date_created: type: string format: date-time readOnly: true required: - change_description - change_sum - change_type - date_created - id EmailFeedbackRequest: type: object description: Request serializer for personal/work email verification feedback. properties: is_correct_person: type: boolean nullable: true name: type: string nullable: true maxLength: 255 person_id: type: integer nullable: true email: type: string format: email writeOnly: true contact_status: $ref: '#/components/schemas/EmailFeedbackRequestContactStatusEnum' required: - contact_status - email EmailFeedbackRequestContactStatusEnum: enum: - valid - invalid type: string description: |- * `valid` - Valid * `invalid` - Invalid EmailFeedbackResponse: type: object description: Response serializer for created personal- and work-email feedback rows. properties: id: type: integer readOnly: true email: type: string readOnly: true contact_status: type: string readOnly: true is_correct_person: type: boolean readOnly: true nullable: true name: type: string readOnly: true nullable: true person_id: type: integer readOnly: true nullable: true date_created: type: string format: date-time readOnly: true required: - contact_status - date_created - email - id - is_correct_person - name - person_id ErrorCodeEnum: enum: - person_not_found - no_current_employer - input_unresolved - provider_error - expired - internal_error type: string description: |- * `person_not_found` - No person matched the LinkedIn identifier * `no_current_employer` - The person has no current employer on record * `input_unresolved` - Submitted input could not be resolved * `provider_error` - Provider error * `expired` - Expired before completion * `internal_error` - Internal error FundingTypesEnum: enum: - angel - convertible_note - corporate_round - debt_financing - equity_crowdfunding - grant - initial_coin_offering - non_equity_assistance - post_ipo_debt - post_ipo_equity - post_ipo_secondary - pre_seed - private_equity - product_crowdfunding - secondary_market - seed - series_a - series_b - series_c - series_d - series_e - series_f - series_g - series_h - series_i - series_j - series_unknown - undisclosed type: string description: |- * `angel` - Angel * `convertible_note` - Convertible Note * `corporate_round` - Corporate Round * `debt_financing` - Debt Financing * `equity_crowdfunding` - Equity Crowdfunding * `grant` - Grant * `initial_coin_offering` - Initial coin offering (ICO) * `non_equity_assistance` - Non-Equity Assistance * `post_ipo_debt` - Post-IPO Debt * `post_ipo_equity` - Post-IPO Equity * `post_ipo_secondary` - Post-IPO Secondary * `pre_seed` - Pre-Seed * `private_equity` - Private Equity * `product_crowdfunding` - Product Crowdfunding * `secondary_market` - Secondary Market * `seed` - Seed * `series_a` - Series A * `series_b` - Series B * `series_c` - Series C * `series_d` - Series D * `series_e` - Series E * `series_f` - Series F * `series_g` - Series G * `series_h` - Series H * `series_i` - Series I * `series_j` - Series J * `series_unknown` - Venture - Series Unknown * `undisclosed` - Undisclosed InnerLocation: type: object description: Serializer for the InnerLocation model. properties: id: type: integer readOnly: true name: type: string maxLength: 255 osm_locations: type: array items: $ref: '#/components/schemas/OSMLocation' readOnly: true required: - id - name - osm_locations JobInnerLocation: type: object description: Serializer for the InnerLocation model for Jobs search API. properties: id: type: integer readOnly: true name: type: string maxLength: 255 osm_locations: type: array items: $ref: '#/components/schemas/JobOSMLocation' readOnly: true required: - id - name - osm_locations JobOSMLocation: type: object description: Serializer for the OSMLocation model for Jobs search API. properties: id: type: integer readOnly: true name: type: string maxLength: 255 place_type: type: string title: Type maxLength: 255 required: - id - name - place_type JobPostEventSearch: type: object description: JobPostEvent search request serializer. properties: page: type: integer job_source: $ref: '#/components/schemas/JobSourceEnum' date_featured_start: type: string format: date date_featured_end: type: string format: date organization_ids: type: array items: type: integer description: >- To get a list of IDs use Organizations lookup endpoint. title: type: string description: This field supports a boolean text search query. description: type: string description: This field supports a boolean text search query. is_remote: type: boolean nullable: true is_active: type: boolean default: true locations: type: array items: type: integer description: >- To get a list of IDs use Locations lookup endpoint. locations_exclude: type: array items: type: integer description: >- To get a list of IDs use Locations lookup endpoint. JobPostEventSearchResponse: type: object description: OrganizationJobPostEvent search response serializer. properties: search_results: type: array items: $ref: '#/components/schemas/JobPostEventSearchResult' readOnly: true total_search_results: type: integer minimum: 0 required: - search_results - total_search_results JobPostEventSearchResult: type: object description: Serializer for the OrganizationJobPostEvent model for Jobs search API. properties: id: type: integer readOnly: true source: allOf: - $ref: '#/components/schemas/Source089Enum' readOnly: true date_featured: type: string format: date organization: allOf: - $ref: '#/components/schemas/ShortOrganization' readOnly: true source_id: type: string maxLength: 65 url: type: string format: uri maxLength: 510 title: type: string maxLength: 255 description: type: string nullable: true is_remote: type: boolean title: Is remote? location: allOf: - $ref: '#/components/schemas/JobInnerLocation' readOnly: true is_active: type: boolean title: Is active? required: - date_featured - id - is_active - is_remote - location - organization - source - source_id - title - url JobPostEventSearchTotalsResponse: type: object description: OrganizationJobPostEvent search totals response serializer. properties: total_search_results: type: integer minimum: 0 required: - total_search_results JobSourceEnum: enum: - indeed - linkedin - angellist type: string description: |- * `indeed` - Indeed * `linkedin` - LinkedIn * `angellist` - AngelList LinkedinIndustry: type: object description: Serializer for the LinkedinIndustry document. properties: id: type: integer readOnly: true name: type: string maxLength: 255 required: - id - name NullEnum: enum: - null OSMLocation: type: object description: Serializer for the OSMLocation model. properties: id: type: integer readOnly: true name: type: string maxLength: 255 place_type: type: string title: Type maxLength: 255 required: - id - name - place_type OrganizationAddress: type: object description: Serializer for the OrganizationAddress model. properties: street_number: type: string nullable: true maxLength: 255 street_name: type: string nullable: true maxLength: 255 city: type: string nullable: true maxLength: 255 state: type: string nullable: true title: State/County maxLength: 255 postcode: type: string nullable: true title: Post/Zip-code maxLength: 64 country: type: string maxLength: 255 summary: type: string required: - country - summary OrganizationFinanceInfo: type: object description: Serializer for the OrganizationFinanceInfo model. properties: revenue: type: integer maximum: 9223372036854776000 minimum: 0 format: int64 nullable: true OrganizationFundingEvent: type: object description: Serializer for the OrganizationFundingEvent model. properties: id: type: integer readOnly: true source: allOf: - $ref: '#/components/schemas/OrganizationFundingEventSourceEnum' readOnly: true date_featured: type: string format: date organization_id: type: integer readOnly: true funding_type: type: string maxLength: 255 funding_total: type: integer maximum: 9223372036854776000 minimum: 0 format: int64 required: - date_featured - funding_total - funding_type - id - organization_id - source OrganizationFundingEventSourceEnum: enum: - crunchbase type: string description: '* `crunchbase` - Crunchbase' OrganizationJobPostEvent: type: object description: Serializer for the OrganizationJobPostEvent model. properties: id: type: integer readOnly: true source: allOf: - $ref: '#/components/schemas/Source089Enum' readOnly: true date_featured: type: string format: date organization_id: type: integer readOnly: true source_id: type: string maxLength: 65 url: type: string format: uri maxLength: 510 title: type: string maxLength: 255 is_remote: type: boolean title: Is remote? is_active: type: boolean title: Is active? required: - date_featured - id - is_active - is_remote - organization_id - source - source_id - title - url OrganizationKeyword: type: object description: Serializer for the OrganizationKeyword model. properties: id: type: integer readOnly: true name: type: string maxLength: 255 required: - id - name OrganizationLinkedinInfo: type: object description: Serializer for the OrganizationLinkedinInfo model. properties: public_identifier: type: string nullable: true maxLength: 255 industry: allOf: - $ref: '#/components/schemas/LinkedinIndustry' readOnly: true public_profile_url: type: string nullable: true description: Get LinkedIn public profile URL. readOnly: true required: - industry - public_profile_url OrganizationPersonRoleSearch: type: object description: OrganizationPersonRole search request serializer. properties: page: type: integer role_title: type: string description: This field supports a boolean text search query. role_description: type: string description: This field supports a boolean text search query. role_is_current: type: boolean default: true role_position_start_date: type: string format: date role_position_end_date: type: string format: date role_years_on_position_start: type: integer role_years_on_position_end: type: integer person_name: type: string description: This field supports a boolean text search query. person_headline: type: string description: This field supports a boolean text search query. person_description: type: string description: This field supports a boolean text search query. person_skills: type: array items: type: integer description: >- To get a list of IDs use Person skills lookup endpoint. person_locations: type: array items: type: integer description: >- To get a list of IDs use Locations lookup endpoint. person_industries: type: array items: type: integer description: >- To get a list of IDs use Industries lookup endpoint. person_industries_exclude: type: array items: type: integer description: >- To get a list of IDs use Industries lookup endpoint. person_linkedin_public_identifiers: type: array items: type: string description: >- LinkedIn person "Public identifier/Slug/ID" - "linkedin.com/in/!slug!/". organizations: type: array items: type: integer description: >- To get a list of IDs use Organizations lookup endpoint. organizations_bulk_domain: type: string organization_domains: type: array items: type: string description: This field supports a boolean text search query. organization_description: type: string description: This field supports a boolean text search query. organization_locations: type: array items: type: integer description: >- To get a list of IDs use Locations lookup endpoint. organization_industries: type: array items: type: integer description: >- To get a list of IDs use Industries lookup endpoint. organization_industries_exclude: type: array items: type: integer description: >- To get a list of IDs use Industries lookup endpoint. organization_keywords: type: array items: type: integer description: >- To get a list of IDs use Organization keywords lookup endpoint. organization_web_technologies: type: array items: type: integer description: >- To get a list of IDs use Web technologies lookup endpoint. organization_founded_date_start: type: string format: date organization_founded_date_end: type: string format: date organization_employees_start: type: integer organization_employees_end: type: integer organization_revenue_start: type: integer organization_revenue_end: type: integer organization_domain_rank_start: type: integer organization_domain_rank_end: type: integer organization_linkedin_public_identifiers: type: array items: type: string description: >- LinkedIn organization "Public identifier/Slug/ID" - "linkedin.com/company/!slug!/". funding_types: type: array items: $ref: '#/components/schemas/FundingTypesEnum' funding_total_start: type: integer funding_total_end: type: integer funding_event_date_featured_start: type: string format: date funding_event_date_featured_end: type: string format: date job_post_title: type: string description: This field supports a boolean text search query. job_post_description: type: string description: This field supports a boolean text search query. job_post_is_remote: type: boolean nullable: true job_post_is_active: type: boolean nullable: true job_post_date_featured_start: type: string format: date job_post_date_featured_end: type: string format: date job_post_locations: type: array items: type: integer description: >- To get a list of IDs use Locations lookup endpoint. job_post_locations_exclude: type: array items: type: integer description: >- To get a list of IDs use Locations lookup endpoint. simple_event_source: $ref: '#/components/schemas/SimpleEventSourceEnum' simple_event_reason: $ref: '#/components/schemas/SimpleEventReasonEnum' simple_event_date_featured_start: type: string format: date simple_event_date_featured_end: type: string format: date OrganizationPersonRoleSearchResult: type: object description: Serializer for OrganizationPersonRole search results. properties: id: type: integer readOnly: true role_title: type: string nullable: true maxLength: 255 start_date: type: string format: date nullable: true end_date: type: string format: date nullable: true duration: type: string nullable: true title: Role duration maxLength: 255 description: type: string nullable: true is_current: type: boolean title: Is current? organization: allOf: - $ref: '#/components/schemas/OrganizationSearchResult' readOnly: true person: allOf: - $ref: '#/components/schemas/PersonChild' readOnly: true date_updated: type: string format: date-time readOnly: true required: - date_updated - id - is_current - organization - person OrganizationSearchRequest: type: object description: Organization search request serializer. properties: page: type: integer organization_ids: type: array items: type: integer description: >- To get a list of IDs use Organizations lookup endpoint. description: type: string locations: type: array items: type: integer description: >- To get a list of IDs use Locations lookup endpoint. industries: type: array items: type: integer description: >- To get a list of IDs use Industries lookup endpoint. industries_exclude: type: array items: type: integer description: >- To get a list of IDs use Industries lookup endpoint. keywords: type: array items: type: integer description: >- To get a list of IDs use Organization keywords lookup endpoint. employees_start: type: integer employees_end: type: integer founded_date_start: type: string format: date founded_date_end: type: string format: date revenue_start: type: integer revenue_end: type: integer domains: type: array items: type: string domain_rank_start: type: integer domain_rank_end: type: integer domain_traffic_start: type: integer domain_traffic_end: type: integer web_technologies: type: array items: type: integer description: >- To get a list of IDs use Web technologies lookup endpoint. linkedin_public_identifiers: type: array items: type: string description: >- LinkedIn organization "Public identifier/Slug/ID" - "linkedin.com/company/!slug!/". funding_types: type: array items: $ref: '#/components/schemas/FundingTypesEnum' funding_total_start: type: integer funding_total_end: type: integer funding_event_date_featured_start: type: string format: date funding_event_date_featured_end: type: string format: date job_post_title: type: string description: This field supports a boolean text search query. job_post_description: type: string description: This field supports a boolean text search query. job_post_is_remote: type: boolean nullable: true job_post_is_active: type: boolean nullable: true job_post_date_featured_start: type: string format: date job_post_date_featured_end: type: string format: date job_post_locations: type: array items: type: integer description: >- To get a list of IDs use Locations lookup endpoint. job_post_locations_exclude: type: array items: type: integer description: >- To get a list of IDs use Locations lookup endpoint. simple_event_source: $ref: '#/components/schemas/SimpleEventSourceEnum' simple_event_reason: $ref: '#/components/schemas/SimpleEventReasonEnum' simple_event_date_featured_start: type: string format: date simple_event_date_featured_end: type: string format: date OrganizationSearchResponse: type: object description: Organization search response serializer. properties: search_results: type: array items: $ref: '#/components/schemas/OrganizationSearchResult' readOnly: true total_search_results: type: integer minimum: 0 required: - search_results - total_search_results OrganizationSearchResult: type: object description: Organization search result(With prefetch events) serializer. properties: id: type: integer readOnly: true name: type: string maxLength: 255 legal_name: type: string maxLength: 255 website: type: string format: uri nullable: true maxLength: 16384 domain: type: string format: uri nullable: true maxLength: 200 domain_rank: type: integer nullable: true description: Domain rank. readOnly: true logo: type: string format: uri nullable: true maxLength: 510 description: type: string nullable: true founded_date: type: string format: date nullable: true operating_status: type: string nullable: true maxLength: 255 employees_range: type: string nullable: true maxLength: 255 employees_amount: type: integer maximum: 2147483647 minimum: 0 nullable: true keywords: type: array items: $ref: '#/components/schemas/OrganizationKeyword' readOnly: true location: allOf: - $ref: '#/components/schemas/InnerLocation' readOnly: true finance_info: allOf: - $ref: '#/components/schemas/OrganizationFinanceInfo' readOnly: true linkedin_info: allOf: - $ref: '#/components/schemas/OrganizationLinkedinInfo' readOnly: true addresses: type: array items: $ref: '#/components/schemas/OrganizationAddress' readOnly: true date_updated: type: string format: date-time readOnly: true found_simple_events: type: array items: $ref: '#/components/schemas/OrganizationSimpleEvent' description: >- Events will be available in case any event field would be used for the search. In results will be available 30 most recent matches. found_funding_events: type: array items: $ref: '#/components/schemas/OrganizationFundingEvent' description: >- Events will be available in case any event field would be used for the search. In results will be available 30 most recent matches. found_job_post_events: type: array items: $ref: '#/components/schemas/OrganizationJobPostEvent' description: >- Events will be available in case any event field would be used for the search. In results will be available 30 most recent matches. required: - addresses - date_updated - domain_rank - finance_info - found_funding_events - found_job_post_events - found_simple_events - id - keywords - legal_name - linkedin_info - location - name OrganizationSearchTotalsResponse: type: object description: Organization search totals response serializer. properties: total_search_results: type: integer minimum: 0 required: - total_search_results OrganizationSimpleEvent: type: object description: Serializer for the OrganizationSimpleEvent model. properties: id: type: integer readOnly: true source: allOf: - $ref: '#/components/schemas/SourceA7bEnum' readOnly: true date_featured: type: string format: date organization_id: type: integer readOnly: true reason: $ref: '#/components/schemas/ReasonEnum' url: type: string format: uri maxLength: 255 required: - date_featured - id - organization_id - reason - source - url PaginatedCreditsBalanceChangeLogList: type: object properties: count: type: integer example: 15 next: type: integer nullable: true example: 2 previous: type: integer nullable: true example: null results: type: array items: $ref: '#/components/schemas/CreditsBalanceChangeLog' PersonCertification: type: object description: Serializer for the PersonCertification model. properties: id: type: integer readOnly: true organization_id: type: integer nullable: true readOnly: true name: type: string maxLength: 510 certificate_id: type: string nullable: true maxLength: 255 url: type: string format: uri nullable: true maxLength: 16384 authority: type: string nullable: true maxLength: 255 required: - id - name - organization_id PersonChild: type: object description: Child serializer for the Person model. properties: id: type: integer readOnly: true full_name: type: string maxLength: 255 first_name: type: string maxLength: 255 last_name: type: string nullable: true maxLength: 255 photo: type: string format: uri nullable: true maxLength: 255 gender: type: string nullable: true maxLength: 255 headline: type: string nullable: true maxLength: 255 description: type: string nullable: true skills: type: array items: $ref: '#/components/schemas/PersonSkill' readOnly: true location: allOf: - $ref: '#/components/schemas/InnerLocation' readOnly: true linkedin_info: allOf: - $ref: '#/components/schemas/PersonLinkedinInfo' readOnly: true date_updated: type: string format: date-time readOnly: true required: - date_updated - first_name - full_name - id - linkedin_info - location - skills PersonCourse: type: object description: Serializer for the PersonCourse model. properties: id: type: integer readOnly: true name: type: string maxLength: 1515 number: type: string nullable: true maxLength: 255 associated_role_id: type: integer nullable: true readOnly: true associated_education_id: type: integer nullable: true readOnly: true required: - associated_education_id - associated_role_id - id - name PersonDetail: type: object description: Person details serializer. properties: id: type: integer readOnly: true full_name: type: string maxLength: 255 first_name: type: string maxLength: 255 last_name: type: string nullable: true maxLength: 255 photo: type: string format: uri nullable: true maxLength: 255 gender: type: string nullable: true maxLength: 255 headline: type: string nullable: true maxLength: 255 description: type: string nullable: true skills: type: array items: $ref: '#/components/schemas/PersonSkill' readOnly: true location: allOf: - $ref: '#/components/schemas/InnerLocation' readOnly: true linkedin_info: allOf: - $ref: '#/components/schemas/PersonLinkedinInfo' readOnly: true roles: type: array items: $ref: '#/components/schemas/PersonRoleChild' educations: type: array items: $ref: '#/components/schemas/PersonEducation' certifications: type: array items: $ref: '#/components/schemas/PersonCertification' readOnly: true courses: type: array items: $ref: '#/components/schemas/PersonCourse' readOnly: true honors: type: array items: $ref: '#/components/schemas/PersonHonor' readOnly: true languages: type: array items: $ref: '#/components/schemas/PersonLanguage' readOnly: true organizations: type: array items: $ref: '#/components/schemas/PersonOrganization' readOnly: true patents: type: array items: $ref: '#/components/schemas/PersonPatent' readOnly: true publications: type: array items: $ref: '#/components/schemas/PersonPublication' readOnly: true test_scores: type: array items: $ref: '#/components/schemas/PersonTestScore' readOnly: true projects: type: array items: $ref: '#/components/schemas/PersonProject' readOnly: true volunteering: type: array items: $ref: '#/components/schemas/PersonVolunteering' readOnly: true required: - certifications - courses - educations - first_name - full_name - honors - id - languages - linkedin_info - location - organizations - patents - projects - publications - roles - skills - test_scores - volunteering PersonEducation: type: object description: Serializer for the PersonEducation model. properties: id: type: integer readOnly: true school_name: type: string maxLength: 255 organization: allOf: - $ref: '#/components/schemas/ShortOrganization' readOnly: true description: type: string nullable: true grade: type: string nullable: true maxLength: 255 degree: type: string nullable: true maxLength: 255 activities: type: string nullable: true maxLength: 255 field_of_study: type: string nullable: true maxLength: 255 start_date: type: string format: date nullable: true end_date: type: string format: date nullable: true required: - id - organization - school_name PersonEmailDetail: type: object description: Person details email serializer, implemented for documentation. properties: email: type: string format: email readOnly: true email_type: type: string readOnly: true validation_status: allOf: - $ref: '#/components/schemas/ValidationStatusEnum' readOnly: true required: - email - email_type - validation_status PersonHonor: type: object description: Serializer for the PersonHonor model. properties: id: type: integer readOnly: true title: type: string maxLength: 510 description: type: string nullable: true issuer: type: string nullable: true issued_on: type: string format: date nullable: true associated_role_id: type: integer nullable: true readOnly: true associated_education_id: type: integer nullable: true readOnly: true required: - associated_education_id - associated_role_id - id - title PersonInfoRequest: type: object description: Person info request serializer. properties: person_id: type: integer linkedin_public_identifier: type: string description: >- LinkedIn organization "Public identifier/Slug/ID" - "linkedin.com/in/!slug!/". PersonLanguage: type: object description: Serializer for the PersonLanguage model. properties: id: type: integer readOnly: true name: type: string maxLength: 255 proficiency: type: string nullable: true maxLength: 255 required: - id - name PersonLinkedinInfo: type: object description: Serializer for the PersonLinkedinInfo model. properties: public_identifier: type: string nullable: true maxLength: 255 industry: allOf: - $ref: '#/components/schemas/LinkedinIndustry' readOnly: true public_profile_url: type: string description: Get LinkedIn public profile URL. readOnly: true required: - industry - public_profile_url PersonOrganization: type: object description: Serializer for the PersonOrganization model. properties: id: type: integer readOnly: true name: type: string title: Title maxLength: 510 description: type: string nullable: true role_title: type: string nullable: true maxLength: 1515 associated_role_id: type: integer nullable: true readOnly: true associated_education_id: type: integer nullable: true readOnly: true required: - associated_education_id - associated_role_id - id - name PersonPatent: type: object description: Serializer for the PersonPatent model. properties: id: type: integer readOnly: true title: type: string maxLength: 510 description: type: string nullable: true patent_number: type: string nullable: true maxLength: 125 application_number: type: string nullable: true maxLength: 255 is_pending: type: boolean url: type: string format: uri nullable: true maxLength: 16384 issued_on: type: string format: date nullable: true filled_on: type: string format: date nullable: true linkedin_inventors_ids: type: array items: type: integer description: Get list of ids of persons who authored this patent. readOnly: true non_linkedin_inventors: type: array items: type: string maxLength: 255 required: - id - is_pending - linkedin_inventors_ids - title PersonPhoneDetail: type: object description: Person details phone number serializer, implemented for documentation. properties: phone_number: type: string readOnly: true required: - phone_number PersonProject: type: object description: Serializer for the PersonProject model. properties: id: type: integer readOnly: true title: type: string maxLength: 510 url: type: string format: uri nullable: true maxLength: 16384 description: type: string nullable: true start_date: type: string format: date nullable: true end_date: type: string format: date nullable: true associated_role_id: type: integer nullable: true readOnly: true associated_education_id: type: integer nullable: true readOnly: true linkedin_contributors_ids: type: array items: type: integer description: Get list of ids of persons who contributed to this project. readOnly: true non_linkedin_contributors: type: array items: type: string maxLength: 255 required: - associated_education_id - associated_role_id - id - linkedin_contributors_ids - title PersonPublication: type: object description: Serializer for the PersonPublication model. properties: id: type: integer readOnly: true name: type: string maxLength: 510 description: type: string nullable: true url: type: string format: uri nullable: true maxLength: 16384 publisher: type: string nullable: true maxLength: 510 published_in: type: string format: date nullable: true linkedin_authors_ids: type: array items: type: integer description: Get list of ids of persons who authored this publication. readOnly: true non_linkedin_authors: type: array items: type: string maxLength: 255 required: - id - linkedin_authors_ids - name PersonReverseSearchByEmail: type: object description: Person reverse search by email request serializer. properties: email: type: string format: email description: The personal email address of the person being searched. required: - email PersonReverseSearchByPhoneNumber: type: object description: Person reverse search by phone number request serializer. properties: phone_number: type: string required: - phone_number PersonRoleChild: type: object description: Child serializer for the OrganizationPersonRole model. properties: id: type: integer readOnly: true role_title: type: string nullable: true maxLength: 255 start_date: type: string format: date nullable: true end_date: type: string format: date nullable: true duration: type: string nullable: true title: Role duration maxLength: 255 description: type: string nullable: true is_current: type: boolean title: Is current? organization: allOf: - $ref: '#/components/schemas/ShortOrganization' readOnly: true organization_name: type: string nullable: true maxLength: 255 required: - id - is_current - organization PersonRoleSearchResponse: type: object description: OrganizationPersonRole search response serializer. properties: search_results: type: array items: $ref: '#/components/schemas/OrganizationPersonRoleSearchResult' readOnly: true total_search_results: type: integer minimum: 0 required: - search_results - total_search_results PersonRoleSearchTotalsResponse: type: object description: OrganizationPersonRole search totals response serializer. properties: total_search_results: type: integer minimum: 0 total_persons: type: integer minimum: 0 total_organizations: type: integer minimum: 0 required: - total_organizations - total_persons - total_search_results PersonSkill: type: object description: Serializer for the PersonSkill model. properties: name: type: string maxLength: 255 required: - name PersonTestScore: type: object description: Serializer for the PersonTestScore model. properties: id: type: integer readOnly: true name: type: string maxLength: 510 description: type: string nullable: true score: type: string nullable: true maxLength: 65 date_on: type: string format: date nullable: true associated_role_id: type: integer nullable: true readOnly: true associated_education_id: type: integer nullable: true readOnly: true required: - associated_education_id - associated_role_id - id - name PersonVolunteering: type: object description: Serializer for the PersonVolunteering model. properties: id: type: integer readOnly: true title: type: string title: Name maxLength: 255 description: type: string nullable: true cause: type: string nullable: true maxLength: 255 organization_name: type: string maxLength: 255 organization_id: type: integer nullable: true readOnly: true start_date: type: string format: date nullable: true end_date: type: string format: date nullable: true required: - id - organization_id - organization_name - title PhoneFeedbackRequest: type: object description: Request serializer for phone-number verification feedback. properties: is_correct_person: type: boolean nullable: true name: type: string nullable: true maxLength: 255 person_id: type: integer nullable: true phone_number: type: string writeOnly: true contact_status: $ref: '#/components/schemas/PhoneFeedbackRequestContactStatusEnum' required: - contact_status - phone_number PhoneFeedbackRequestContactStatusEnum: enum: - connected - disconnected type: string description: |- * `connected` - Connected * `disconnected` - Disconnected PhoneFeedbackResponse: type: object description: Response serializer for created phone feedback rows. properties: id: type: integer readOnly: true phone_number: type: string readOnly: true contact_status: type: string readOnly: true is_correct_person: type: boolean readOnly: true nullable: true name: type: string readOnly: true nullable: true person_id: type: integer readOnly: true nullable: true date_created: type: string format: date-time readOnly: true required: - contact_status - date_created - id - is_correct_person - name - person_id - phone_number ReasonEnum: enum: - report_released - promoted_on_site type: string description: |- * `report_released` - Report released * `promoted_on_site` - Promoted on site ShortOrganization: type: object description: Short serializer for the Organization model. properties: id: type: integer readOnly: true name: type: string maxLength: 255 domain: type: string format: uri nullable: true maxLength: 200 linkedin_info: allOf: - $ref: '#/components/schemas/OrganizationLinkedinInfo' readOnly: true required: - id - linkedin_info - name SimpleEventReasonEnum: enum: - report_released - promoted_on_site type: string description: |- * `report_released` - Report released * `promoted_on_site` - Promoted on site SimpleEventSourceEnum: enum: - product_hunt - form_c_sec_gov - form_d_sec_gov type: string description: |- * `product_hunt` - Product Hunt * `form_c_sec_gov` - Form C sec.gov * `form_d_sec_gov` - Form D sec.gov Source089Enum: enum: - indeed - linkedin - angellist type: string description: |- * `indeed` - Indeed * `linkedin` - LinkedIn * `angellist` - AngelList SourceA7bEnum: enum: - product_hunt - form_c_sec_gov - form_d_sec_gov type: string description: |- * `product_hunt` - Product Hunt * `form_c_sec_gov` - Form C sec.gov * `form_d_sec_gov` - Form D sec.gov Status564Enum: enum: - queued - running - awaiting_provider - completed - failed type: string description: |- * `queued` - Queued * `running` - Running * `awaiting_provider` - Awaiting provider * `completed` - Completed * `failed` - Failed StripeSubscriptionPrice: type: object description: Stripe subscription price serializer. properties: id: type: integer readOnly: true plan_price_usd: type: string format: decimal pattern: ^-?\d{0,8}(?:\.\d{0,2})?$ title: Plan price (USD) min_credits: type: integer maximum: 2147483647 minimum: 0 billing_cycle: $ref: '#/components/schemas/BillingCycleEnum' required: - id Subscription: type: object description: Subscription serializer. properties: id: type: integer readOnly: true is_active: type: boolean title: Is active? credits_balance: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,2})?$ readOnly: true subscription_tier: allOf: - $ref: '#/components/schemas/SubscriptionTier' readOnly: true stripe_subscription_id: type: string nullable: true maxLength: 65 stripe_subscription_price: allOf: - $ref: '#/components/schemas/StripeSubscriptionPrice' readOnly: true required: - credits_balance - id - stripe_subscription_price - subscription_tier SubscriptionTier: type: object description: Subscription tier serializer. properties: id: type: integer readOnly: true name: type: string maxLength: 35 person_details_lookup: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,2})?$ person_work_email_lookup: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,2})?$ person_personal_email_lookup: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,2})?$ person_phone_number_lookup: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,2})?$ person_reverse_email_search: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,2})?$ person_reverse_phone_number_search: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,2})?$ person_role_details_lookup: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,2})?$ person_role_search_api_call: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,2})?$ job_search_api_call: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,2})?$ organization_search_api_call: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,2})?$ organization_technologies_lookup: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,2})?$ features: type: array items: $ref: '#/components/schemas/SubscriptionTierFeature' readOnly: true stripe_subscription_prices: type: array items: $ref: '#/components/schemas/StripeSubscriptionPrice' readOnly: true required: - features - id - name - stripe_subscription_prices SubscriptionTierFeature: type: object description: Subscription tier feature serializer. properties: description: type: string maxLength: 255 required: - description TotalCreditsSpent: type: object description: >- Declares JSON representation of `CreditsBalanceChangeLogsView.total_credits_spent()` action response. properties: total_credits_spent: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,2})?$ required: - total_credits_spent User: type: object description: Account user serializer. properties: id: type: integer readOnly: true username: type: string description: >- Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only. pattern: ^[\w.@+-]+$ maxLength: 150 email: type: string format: email title: Email address maxLength: 254 first_name: type: string maxLength: 150 last_name: type: string maxLength: 150 accounts: type: array items: $ref: '#/components/schemas/Account' readOnly: true required: - accounts - email - id - username ValidationStatusEnum: enum: - valid - risky - invalid - unknown type: string description: |- * `valid` - Valid * `risky` - Risky * `invalid` - Invalid * `unknown` - Unknown WebSite: type: object description: WebSite serializer. properties: id: type: integer readOnly: true domain: type: string format: uri maxLength: 200 tranco_rank: type: integer maximum: 2147483647 minimum: 0 nullable: true description: The Tranco three month average traffic rank similarweb_rank: type: integer maximum: 2147483647 minimum: 0 nullable: true similarweb_traffic: type: integer maximum: 9223372036854776000 minimum: 0 format: int64 nullable: true website_technologies: type: array items: $ref: '#/components/schemas/WebSiteTechnology' readOnly: true required: - domain - id - website_technologies WebSiteLookupRequest: type: object description: WebSite lookup API request serializer. properties: domain: type: string organization_id: type: integer organization_linkedin_public_identifier: type: string WebSiteTechnology: type: object description: WebSiteTechnology serializer. properties: web_technology_id: type: integer readOnly: true is_active: type: boolean title: Is active? name: type: string description: Get WebTechnology name. readOnly: true required: - name - web_technology_id WorkEmailBatch: type: object description: >- A batch and, once it is finished, everything it found. One endpoint rather than two: polling a batch and reading its results are done together. `results` stays empty until the batch is `completed`, so it is never a partial answer that looks like a whole one, and comes back **in submitted order** so it lines up with the array that was sent. `resolved_from_cache` and `rejected` are recorded on the batch but not returned. How much of a batch we served without paying a vendor is our business, and a bare count of rejected rows is not actionable now that each one is a result in its own right, carrying its own `error_code`. properties: batch_id: type: string format: uuid readOnly: true status: allOf: - $ref: '#/components/schemas/WorkEmailBatchStatusEnum' readOnly: true item_count: type: integer description: How many rows this batch holds. readOnly: true date_created: type: string format: date-time readOnly: true date_completed: type: string format: date-time readOnly: true nullable: true results: type: array items: $ref: '#/components/schemas/WorkEmailBatchItem' readOnly: true required: - batch_id - date_completed - date_created - item_count - results - status WorkEmailBatchItem: type: object description: >- A batch result: a job plus the `index` it held in the submitted array. `index` belongs to the batch shape only - a single submit has no array to be an index into - so it is added here rather than on the base job serializer the single poll uses. properties: submitted_index: type: integer readOnly: true description: >- Zero-based position of this row in the `email_lookups` array you submitted, so results can be matched back to your input order. job_id: type: string format: uuid readOnly: true status: allOf: - $ref: '#/components/schemas/Status564Enum' readOnly: true emails: type: array items: type: string minLength: 2 maxLength: 2 description: >- Every confirmed address for this person, shortest first, each with its verdict. readOnly: true error_code: readOnly: true nullable: true oneOf: - $ref: '#/components/schemas/ErrorCodeEnum' - $ref: '#/components/schemas/NullEnum' person_id: type: integer readOnly: true nullable: true submitted_lookup: type: object description: >- Echo the row exactly as it was sent. Nested rather than four top-level fields, so "what you sent" is never confused with "what we searched", and so the top level keeps its rule that an absent value is `null` - here a blank string is the honest echo. Spelled out key by key rather than dumped from the stored model, so a new column on `SubmittedFields` becomes a deliberate addition here instead of appearing in the response unasked. properties: first_name: type: string last_name: type: string domain: type: string linkedin_public_identifier: type: string required: - domain - first_name - last_name - linkedin_public_identifier readOnly: true date_created: type: string format: date-time readOnly: true date_completed: type: string format: date-time readOnly: true nullable: true result: type: string readOnly: true required: - date_completed - date_created - emails - error_code - job_id - person_id - result - status - submitted_index - submitted_lookup WorkEmailBatchStatusEnum: enum: - queued - running - completed - failed type: string description: |- * `queued` - Queued * `running` - Running * `completed` - Completed * `failed` - Failed WorkEmailBatchSubmitted: type: object description: >- The `202` body of a bulk submit: the batch, where to poll it, and the webhook echo. A serializer of its own rather than the batch poll serializer, so the 202 can carry `status_check_url` and echo `webhook_url` without either leaking onto the poll response, which must never return the caller's secret-bearing URL. `results` is empty at submit and documented here only for shape. properties: batch_id: type: string format: uuid readOnly: true status: type: string readOnly: true item_count: type: integer readOnly: true date_created: type: string format: date-time readOnly: true date_completed: type: string format: date-time readOnly: true nullable: true status_check_url: type: string readOnly: true webhook_url: type: string readOnly: true results: type: array items: $ref: '#/components/schemas/WorkEmailBatchItem' readOnly: true required: - batch_id - date_completed - date_created - item_count - results - status - status_check_url - webhook_url WorkEmailBulkRequest: type: object description: >- A batch of work email lookups, with an optional batch-scoped result webhook. properties: email_lookups: type: array items: $ref: '#/components/schemas/WorkEmailLookupRequest' minItems: 1 webhook_url: type: string default: '' description: >- Optional https URL we POST the results to when the batch completes, so you need not poll. Put any secret used to authenticate the callback in the URL query string; it is never returned by the poll endpoints or written to logs. Omit to poll only. maxLength: 2048 required: - email_lookups WorkEmailLookupJob: type: object description: >- The envelope every lookup result is returned in, single or bulk. Narrower than the model: the vendor, the verification count and the miss reason are recorded but never returned, since they expose how the waterfall is built and would make swapping a provider a breaking change. `status` is how far a lookup got; `result` is what it concluded, and is `null` on a row that never ran. `emails` is not a column on the job - it comes from the `PersonWorkEmail` rows sharing its `lookup_key`, read from a map in the serializer context so a batch costs one cross-database query rather than one per row. Each entry carries its own `validation_status`, since a person's addresses can be verified separately. properties: job_id: type: string format: uuid readOnly: true status: allOf: - $ref: '#/components/schemas/Status564Enum' readOnly: true emails: type: array items: type: string minLength: 2 maxLength: 2 description: >- Every confirmed address for this person, shortest first, each with its verdict. readOnly: true error_code: readOnly: true nullable: true oneOf: - $ref: '#/components/schemas/ErrorCodeEnum' - $ref: '#/components/schemas/NullEnum' person_id: type: integer readOnly: true nullable: true submitted_lookup: type: object description: >- Echo the row exactly as it was sent. Nested rather than four top-level fields, so "what you sent" is never confused with "what we searched", and so the top level keeps its rule that an absent value is `null` - here a blank string is the honest echo. Spelled out key by key rather than dumped from the stored model, so a new column on `SubmittedFields` becomes a deliberate addition here instead of appearing in the response unasked. properties: first_name: type: string last_name: type: string domain: type: string linkedin_public_identifier: type: string required: - domain - first_name - last_name - linkedin_public_identifier readOnly: true date_created: type: string format: date-time readOnly: true date_completed: type: string format: date-time readOnly: true nullable: true result: type: string readOnly: true required: - date_completed - date_created - emails - error_code - job_id - person_id - result - status - submitted_lookup WorkEmailLookupRequest: type: object description: >- One work email lookup request. The `domain` decides how the person is identified: * **with** a domain, `first_name` and `last_name` are both required; * **without** one, `linkedin_public_identifier` is required, and the name and the employer domain are taken from the record it resolves. A domain and an identifier together is refused: they can disagree about which company to search, and the answer would be unattributable. properties: first_name: type: string default: '' last_name: type: string default: '' domain: type: string default: '' description: >- Company domain, e.g. "acme.com". A full URL is accepted and reduced to its domain. linkedin_public_identifier: type: string default: '' description: >- LinkedIn person "Public identifier/Slug" - "linkedin.com/in/!slug!/". WorkEmailLookupSubmitRequest: type: object description: >- The single-submit body: one lookup, plus an optional result webhook. Kept apart from the bulk child `WorkEmailLookupRequestSerializer` so `webhook_url` sits beside the lookup on a single submit but never appears on each row of a bulk request, where the target is batch-scoped instead. properties: first_name: type: string default: '' last_name: type: string default: '' domain: type: string default: '' description: >- Company domain, e.g. "acme.com". A full URL is accepted and reduced to its domain. linkedin_public_identifier: type: string default: '' description: >- LinkedIn person "Public identifier/Slug" - "linkedin.com/in/!slug!/". webhook_url: type: string default: '' description: >- Optional https URL we POST the results to when the batch completes, so you need not poll. Put any secret used to authenticate the callback in the URL query string; it is never returned by the poll endpoints or written to logs. Omit to poll only. maxLength: 2048 WorkEmailLookupSubmitted: type: object description: The `202` body of a single submit. properties: job_id: type: string format: uuid readOnly: true status: type: string readOnly: true status_check_url: type: string readOnly: true webhook_url: type: string readOnly: true required: - job_id - status - status_check_url - webhook_url securitySchemes: Api-Key: type: apiKey in: header name: X-API-KEY servers: - url: https://api-v2.forager.ai tags: - name: Job Posts description: >- 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. - name: Organizations description: >- 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. - name: People description: >- Look up people and their records. Use the search endpoints to find people by role, employer, location, or skills, and the detail-lookup endpoints to fetch a full person record by ID, email, or phone number. Contact data has its own sections: Phones, Personal Emails, and Work Emails. - name: Phones description: >- Retrieve phone numbers for a known person. Provide identifying information (such as a LinkedIn handle or Forager ID) and get back the available phone numbers. - name: Personal Emails description: >- Retrieve personal email addresses for a known person. Returns addresses on free webmail / consumer providers (Gmail, Outlook, Yahoo, iCloud, Proton, and similar); corporate, educational, and other custom domains are excluded to keep deliverability high. - name: Work Emails description: >- Find and verify a person's work email address. Submit a lookup (single or bulk), poll the job for its result, and optionally receive the result by webhook when the job completes. - name: Websites description: >- Look up information about a website, including the organization that owns it and the technologies detected on the domain. - name: Users description: >- 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. - name: Autocomplete description: >- 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. - name: Feedback description: >- 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.