Delpha

Submit an asynchronous job to find and validate the LinkedIn page of a COMPANY: send `url` to validate one, or `company_name` (with `website` for precision) to search for one. Returns a `job_id` — pass it to `getLinkedInCompanyPageResult` to retrieve the canonical page URL plus accuracy and validity scores. Two modes: - Validate an existing page — supply `url`. - Search — supply `company_name`, adding `website` for precision. `findAndValidateLinkedInProfile` covers a PERSON — this operation looks for `/company/`, `/school/` and `/showcase/` pages only. These results are processed from the company website and from public web search: Google results, retrieved through Google Custom Search API or a SERP provider. No LinkedIn account, session or credential is used, and no third-party database is consulted. The company name and country you supply are sent to that search provider, and the company website you supply — or the domain of an email address you supply, which itself never leaves Delpha — is requested directly. A URL you submit for validation is never requested: its format is checked, and it may be searched for through that search provider. **Cost:** an accepted call spends 1 credit and starts a new job; a repeat with the same input starts another and is charged again. The call and its result are kept in your team's resolution history for its configured retention.

findAndValidateLinkedInCompanyPage

Submit an asynchronous job to find and validate the LinkedIn profile of a PERSON: send `url` to validate one, or `first_name` and `last_name` with `company_name` or `website` to search for one. Returns a `job_id` — pass it to `getLinkedInProfileResult` to retrieve the canonical profile URL plus accuracy and validity scores. Two modes: - Validate an existing profile — supply `url`. - Search — supply `first_name` + `last_name` plus company context (`company_name` and/or `website`); an `email` contributes only its domain, as `website` would. Company context narrows the search among people who share a name; without it a namesake can rank first, and for a very common name a namesake can rank first even with it. `findAndValidateLinkedInCompanyPage` covers a COMPANY's page — this operation looks for `/in/` profiles only. The search is built only from the fields in this request; nothing carries over from a previous job. These results are processed in real time from public web search: Google results, retrieved through Google Custom Search API or a SERP provider. No LinkedIn account, session or credential is used, and no contact database or third-party database is consulted. The name, company and country you supply are sent to that search provider. An email address you supply never leaves Delpha: only its domain is used, as a company website, and a company website is requested directly only when no name is given. A URL you submit for validation is never requested: its format is checked, and it may be searched for through that search provider. **Cost:** an accepted call spends 1 credit and starts a new job; a repeat with the same input starts another and is charged again. The call and its result are kept in your team's resolution history for its configured retention.

findAndValidateLinkedInProfile

Submit an asynchronous job to find and validate a company's legal identifier (SIRET, SIREN, NZBN, ABN, CIK, ...): send `legal_id` to validate one or `name` to search for one, plus `legal_id_type` or `address.country` to select the registry. The identifier is a business registry number, never a personal identifier. Returns a `job_id` — pass it to `getLegalIDResult` to retrieve the normalized identifier, the resolved `legal_id_type`, and validity / accuracy scores. **Registry selection:** the job targets one registry, resolved from either of two fields: - `legal_id_type` — the registry directly (e.g. `FRA - SIRET`, `GBR - COMPANY REGISTRATION NUMBER`), or - `address.country` — the entity's country, from which the registry is inferred. A call that provides neither is rejected with 400 (`Either 'legal_id_type' or 'address.country' must be provided`) — e.g. `{name, website}` alone fails. The remaining fields select the mode: `legal_id` runs validation and `name` runs search — a call with neither is rejected with 400; `website` only adds a country signal. **Coverage:** only the registries in the `legal_id_type` enum can be queried. A request naming any other registry, or a country that has no registry in that list, is refused with **422 `unsupported_registry`** *before any credit is reserved*; the message lists the supported countries. That refusal depends only on the registry or country requested, so the same country returns it again whatever `name` or `legal_id` carries. An explicit `legal_id_type` takes precedence over `address.country`, so a supported registry with an unsupported country still runs. The name or identifier you supply is matched against Delpha's company datalake and, when needed, the public registry of the selected country. A company found in a registry is added to the datalake. **Cost:** an accepted call spends 1 credit and starts a new job; a repeat with the same input starts another and is charged again. The call and its result are kept in your team's resolution history for its configured retention.

findAndValidateLegalID

Resolve a company's ultimate parent from one of its subsidiaries, brands or divisions: send `company_name` and `website`, both required. The parent returned is the **commercial parent**: the operating group the company is sold to and routed under. Passive holding entities set aside on the way up are flagged `is_discarded` in the ownership chain, and when a financial owner such as a fund sits above the operating group it is returned separately as `ultimate_financial_parent`. The result also carries the full ownership chain, the relationship type and a confidence score; each entity carries GLEIF metadata in `lei_data` when a match is found, `null` when none is. The resolution is anchored on the company's website, not on its name alone: the website binds the name to one specific entity and seeds the search. Ownership is resolved from a live web search plus GLEIF/LEI lookups, not from a static database. Async: poll `getUltimateParentResult` with the returned `job_id`. The company name, website and country you supply are sent to Delpha's AI providers, which search the web; the parent found is checked against GLEIF's public LEI register. **Cost:** an accepted call spends 1 credit and starts a new job; a repeat with the same input starts another and is charged again. The call and its result are kept in your team's resolution history for its configured retention.

findAndValidateUltimateParent

Submit an asynchronous job to find and validate a company's website: send `website` to validate one, or `name` with `country` (or `linkedin`) to search for one. Returns a `job_id` — pass it to `getWebsiteResult` to retrieve the canonical URL plus accuracy, validity, completeness, and consistency scores. Two modes: - Validate an existing URL — supply `website`. The tool checks reachability and matches the site against the other entity signals. A redirect destination is adopted when it shares the input's registrable domain, when the evidence ranks it above the original, or when a scored search candidate corroborates it; otherwise the normalized input is kept. - Search — supply entity signals (`name` + `country`, or `linkedin`; a bare domain sent as `website` is validated instead) and the tool finds the most likely website. `country` materially improves accuracy and disambiguates same-named companies across regions. Optional. The name and country you supply are sent to a web-search provider and to Delpha's AI provider. A website you supply, or one found by search, is visited to check it. **Cost:** an accepted call spends 1 credit and starts a new job; a repeat with the same input starts another and is charged again. The call and its result are kept in your team's resolution history for its configured retention.

findAndValidateWebsite

Find, validate, and qualify a person's email address: send `email` to verify it, or `first_name`, `last_name` and `website` together to search for it. Submit an asynchronous job; the returned `job_id` goes to `getEmailResult`, which yields the validated email, the `email_status` (Valid / ...), `email_domain_qualification` (whether the address's domain is a public/personal mail domain or a company domain, and whether it accepts mail at any address; see `getEmailResult`), the qualified domain, the scores (validity / completeness / accuracy / consistency), and ranked suggestions (both inferred from the input and from the company website). Two modes — at least one must be fully satisfied: - Validation mode: provide `email` alone to verify deliverability and qualify the domain. - Recommendation mode: provide `first_name`, `last_name`, AND `website` together (all three required) to search for the address. Partial recommendation inputs are rejected with 400. Supplying both an email and the recommendation triple runs both paths in the same job. This result comes from Delpha's own verification and a Delpha model; no contact database and no third-party database is used. Candidate addresses are generated from per-domain address patterns, not retrieved from a list of known addresses. The address you supply — or an address formed from the name and company website you supply — reaches the mail infrastructure of that address's own domain. **Cost:** an accepted call spends 1 credit and starts a new job; a repeat with the same input starts another and is charged again. The call and its result are kept in your team's resolution history for its configured retention.

findAndValidateEmail

Fetch the result of a previously submitted `findAndValidateLinkedInCompanyPage` job by `job_id`. On success, the `result` payload contains the canonical company page URL, accuracy and validity scores, and a `recommendations` array of candidate pages (each carrying `url`, `headline`, `desc`, `company_name`, `location`, and a confidence `score`) when the match is uncertain. In search mode the top-level `label` and scores are often `"No"` and 0 while `recommendations` still holds the candidates. Each candidate carries a `desc` and a `headline`; unrelated companies can share a name across countries, so those two fields are what tell them apart. **Result fields** (`result`, populated once `status_code == 200`): - `data_type` (string): The type of data for this field. One of: `email`, `social_network`, `name`, `legal_id`, `phone`, `address`, `website`. - `normalized_value` (string): Normalized LinkedIn company page URL. - `label` (string): Label for the LinkedIn value. One of: `No`, `OK`, `Unknown`. - `scores` (ScoresModel): Scores for the field. - `accuracy` (number): Accuracy score - `validity` (integer): Validity score - `completeness` (number): Completeness score - `consistency` (integer): Consistency score - `recommendations` (array of LinkedInCompanyPageRecommendation): Candidate company pages, best first. - `url` (string): Recommended LinkedIn company page URL (a `/company/`, `/school/` or `/showcase/` page). - `score` (number): Confidence score for the recommendation. - `headline` (string, nullable): The search result's headline — the title line Google renders for this page, usually the page name. - `rank` (integer, nullable): Rank of the recommendation. - `desc` (string, nullable): Description of the recommended page, as the search result renders it. - `company_name` (string, nullable): Company name shown on the recommended page. - `location` (string, nullable): Location shown on the recommended page. - `match_score` (number, nullable): Pure match quality of this candidate against the company in the request, before the ambiguity division. `score` = `match_score / ambiguity_n`. - `ambiguity_n` (integer, nullable): How many candidates scored within 10% of the best match. Greater than 1 means several pages match comparably well and the divided `score` reflects that ambiguity, not a poor match. - `recommendation_status` (string, nullable): Reading of the recommendation situation: 'confident' (one clear winner), 'ambiguous' (several candidates match comparably well — see each candidate's ambiguity_n), or 'no_match' (no credible page found). Vocabulary may grow; treat unknown values as informational. - `type` (string, nullable): The social network the assessed value belongs to. Always `linkedin` on these operations — Delpha assesses no other network today — it is provenance, not a discriminator. **Envelope:** `status_code` `200` means the job succeeded and `result` is populated; `202` means it is still running and `result` is `null`. A failed job comes back with `status` `"ERROR"`, its `status_code`, a stable `code` naming the cause and a `message` explaining it; an unknown or expired `job_id` is answered as a tool error. **Polling:** the MCP server holds this call and re-polls the job internally for up to ~25 seconds (this validation typically completes in ~10 seconds), so one call usually returns the final result. If `status_code` is still `202` after that, the job is still running and this tool accepts the same job id again. Re-reading a result never re-runs or re-charges the job. **Cost:** no new charge. Reading a result finalizes the job's accounting once: it settles the charge made at submission when the result is first delivered, or refunds it when the job failed, exceeded its time limit or produced no usable result, and marks a timed-out job failed. A repeat returns the same answer and never charges again.

getLinkedInCompanyPageResult

Fetch the result of a previously submitted `findAndValidateLinkedInProfile` job by `job_id`. On success, the `result` payload contains the canonical profile URL, accuracy and validity scores, and a `recommendations` array of candidate profiles (each carrying `url`, `headline`, `desc`, `company_name`, `location`, `profile_name`, and a confidence `score`) when the match is uncertain. In search mode the top-level `label` and scores are often `"No"` and 0 while `recommendations` still holds the candidates. A namesake can outrank the intended person even when company context was supplied, so `recommendations[0]` is a ranked candidate rather than a confirmed match; each candidate's `company_name` and `desc` are what distinguish one from another. **Result fields** (`result`, populated once `status_code == 200`): - `data_type` (string): The type of data for this field. One of: `email`, `social_network`, `name`, `legal_id`, `phone`, `address`, `website`. - `normalized_value` (string): Normalized LinkedIn profile URL. - `label` (string): Label for the LinkedIn value. One of: `No`, `OK`, `Unknown`. - `scores` (ScoresModel): Scores for the field. - `accuracy` (number): Accuracy score - `validity` (integer): Validity score - `completeness` (number): Completeness score - `consistency` (integer): Consistency score - `recommendations` (array of LinkedInRecommendation): Candidate profiles, best first. - `url` (string): Recommended LinkedIn profile URL. - `score` (number): Confidence score for the recommendation. - `headline` (string, nullable): The search result's headline — the title line Google renders for this profile, usually 'Name - job title - company'. ⚠️ This is NOT LinkedIn's 'headline' profile field — that is `job_title`. - `rank` (integer, nullable): Rank of the recommendation. - `desc` (string, nullable): Description of the recommended profile, as the search result renders it. - `company_name` (string, nullable): Company the person works at, as the recommended profile shows it. - `location` (string, nullable): Location shown on the recommended profile. - `profile_name` (string, nullable): The person's name on the recommended profile. - `job_title` (string, nullable): Job title of the recommended profile, as LinkedIn shows it. Usually taken from the structured job-title slot of the search result; when that is absent it falls back to the profile's LinkedIn headline, so it can read as free text ('Fortune 100 Executive | P&L Leader') rather than a clean role, and Google sometimes clips it with an ellipsis. Null when the search result carried no job title. - `match_score` (number, nullable): Pure match quality of this candidate against the person in the request, before the ambiguity division. `score` = `match_score / ambiguity_n`. - `ambiguity_n` (integer, nullable): How many candidates scored within 10% of the best match. Greater than 1 means several profiles match comparably well and the divided `score` reflects that ambiguity, not a poor match. - `recommendation_status` (string, nullable): Reading of the recommendation situation: 'confident' (one clear winner), 'ambiguous' (several candidates match comparably well — see each candidate's ambiguity_n), or 'no_match' (no credible profile found). Vocabulary may grow; treat unknown values as informational. - `fallback_used` (boolean, nullable): True when the emitted recommendations come from the name-only fallback search: no credible profile was found at the queried company, but same-name profiles exist elsewhere (a possible job-change signal). - `url_changed` (boolean, nullable): True when the submitted profile URL is probably outdated: it was not found, while exactly one other profile matching the person was found with confidence. LinkedIn does not redirect a profile whose address was changed, so the old address stops working. The replacement is in `suggested_url`. - `suggested_url` (string, nullable): The profile that probably replaces an outdated submitted URL, set only when `url_changed` is true. It is also the first recommendation. - `type` (string, nullable): The social network the assessed value belongs to. Always `linkedin` on these operations — Delpha assesses no other network today — it is provenance, not a discriminator. **Envelope:** `status_code` `200` means the job succeeded and `result` is populated; `202` means it is still running and `result` is `null`. A failed job comes back with `status` `"ERROR"`, its `status_code`, a stable `code` naming the cause and a `message` explaining it; an unknown or expired `job_id` is answered as a tool error. **Polling:** the MCP server holds this call and re-polls the job internally for up to ~25 seconds (this validation typically completes in ~10 seconds), so one call usually returns the final result. If `status_code` is still `202` after that, the job is still running and this tool accepts the same job id again. Re-reading a result never re-runs or re-charges the job. **Cost:** no new charge. Reading a result finalizes the job's accounting once: it settles the charge made at submission when the result is first delivered, or refunds it when the job failed, exceeded its time limit or produced no usable result, and marks a timed-out job failed. A repeat returns the same answer and never charges again.

getLinkedInProfileResult

Fetch the result of a previously submitted `findAndValidateEmail` job by `job_id`. On success, the `result` payload contains: the validated email (`normalized_value`); `email_status` (closed enum: `"Valid"`, `"Invalid"`, `"Unknown"`); `email_domain_qualification`, which reports two properties of the address's domain — whether it is a public/personal mail domain or a company domain, and whether it accepts mail at any address (closed enum: `"nominative@perso"` = a public/personal mail domain that rejects unknown addresses; `"catchall@perso"` = a public/personal mail domain that accepts any address; `"nominative@pro"` = a company domain that rejects unknown addresses; `"catchall@pro"` = a company domain that accepts any address, so acceptance is not evidence the mailbox exists; `"Unknown"` = the domain could not be classified, for instance because it greylisted the probe or its server failed temporarily); a top-level `label` summarising the outcome (closed enum: `"OK"`, `"No"`, `"OddFormat"`); the qualified domain; the four `scores` (validity, completeness, accuracy, consistency); and ranked `suggestions` (alternative addresses scored by likelihood) when no exact match is found. **Result fields** (`result`, populated once `status_code == 200`): - `label` (string): Label for the email. One of: `No`, `OK`, `OddFormat`. - `normalized_value` (string): Normalized email value. - `provider` (string, nullable): Provider of the email, if any. - `email_domain` (string, nullable): Domain of the email. `null` when the address carries no parseable domain (a syntactically invalid address, which returns `label: "No"`). - `email_domain_qualification` (string): Qualification of the email domain. One of: `nominative@pro`, `catchall@pro`, `nominative@perso`, `catchall@perso`, `Unknown`. - `email_status` (string): Status of the email. Possible values: 'Invalid', 'Unknown', 'Valid'. One of: `Invalid`, `Unknown`, `Valid`. - `email_address_qualification` (string, nullable): Address-level qualification of the mailbox, when one applies: `Spam Trap` (an address Delpha holds on a list of addresses used to detect unsolicited mail rather than read by a person) or `Role-based` (a shared functional mailbox such as `contact@`/`support@`, not a person). `null` means neither applies. ⚠️ This takes precedence over `email_domain_qualification`, which describes the DOMAIN rather than this address: a `Role-based` mailbox on a nominative professional domain is still role-based. The vocabulary may grow, so an unrecognised value is informational rather than an error. - `suggestions` (array of EmailSuggestion): Suggestions for the email. - `value` (string): Suggested email value. - `score` (number): Confidence score for the suggestion. - `website_domain` (string, nullable): Website domain associated. - `website_domain_qualification` (string, nullable): Qualification of the website domain. One of: `nominative@pro`, `catchall@pro`, `nominative@perso`, `catchall@perso`, `Unknown`. - `suggestions_from_website` (array of EmailSuggestion): Suggestions from the website. Fields as in `suggestions`. - `data_type` (string): The type of data for this field One of: `email`, `social_network`, `name`, `legal_id`, `phone`, `address`, `website`. - `scores` (ScoresModel): Scores for the field - `accuracy` (number): Accuracy score - `validity` (integer): Validity score - `completeness` (number): Completeness score - `consistency` (integer): Consistency score **Envelope:** `status_code` `200` means the job succeeded and `result` is populated; `202` means it is still running and `result` is `null`. A failed job comes back with `status` `"ERROR"`, its `status_code`, a stable `code` naming the cause and a `message` explaining it; an unknown or expired `job_id` is answered as a tool error. **Polling:** the MCP server holds this call and re-polls the job internally for up to ~180 seconds (this validation typically completes in ~5 seconds), so one call usually returns the final result. If `status_code` is still `202` after that, the job is still running and this tool accepts the same job id again. Re-reading a result never re-runs or re-charges the job. **Cost:** no new charge. Reading a result finalizes the job's accounting once: it settles the charge made at submission when the result is first delivered, or refunds it when the job failed, exceeded its time limit or produced no usable result, and marks a timed-out job failed. A repeat returns the same answer and never charges again.

getEmailResult

Fetch the result of a previously submitted `findAndValidateLegalID` job by `job_id`. On success, the `result` payload contains the normalized legal identifier, the resolved `legal_id_type` (which registry it belongs to), the validity / accuracy scores, a `match` object with the enriched company record (account name, address, annual revenue, employee count, industry, formation date, company type, website) when a confident match is found, and a `suggestions` array of alternative company records each ranked by confidence. **Result fields** (`result`, populated once `status_code == 200`): - `data_type` (string): The type of data for this field One of: `email`, `social_network`, `name`, `legal_id`, `phone`, `address`, `website`. - `normalized_value` (string): Normalized legal ID value. - `label` (string): Label for the legal ID. One of: `No`, `OK`, `Unknown`. - `legal_id_type` (string, nullable): The type of legal ID. Free-form: it normally matches one of the types accepted on submission. Null when no registry could be determined. - `scores` (ScoresModel): Scores for the field - `accuracy` (number): Accuracy score - `validity` (integer): Validity score - `completeness` (number): Completeness score - `consistency` (integer): Consistency score - `match` (LegalIDSuggestion, nullable): The match information - `score` (number): Confidence score for the suggestion. - `account_name` (string): The account name - `industry` (IndustryModel, nullable): The industry information - `website` (Website, nullable): The website - `address` (LegalIDAddress, nullable): The address information - `financials` (Financials, nullable): Filed financial figures for the company's most recent fiscal period, as published by its national register. Replaces the former `annual_revenue` field, which is no longer returned. - `employees_nb` (EmployeesNbModel, nullable): The employee number information - `source` (string, nullable): The source URL - `company_type` (CompanyTypeModel, nullable): The company type information - `date` (DateModel, nullable): The date information - `legal_id_type` (string): The legal ID type. Free-form: it normally matches one of the types accepted on submission, but a record sourced from the datalake may carry a historical type. - `legal_id` (string): The legal ID - `headquarters_site` (HeadquartersSite, nullable): The suggested entity's headquarters site, with its legal identifier — resolved from the datalake's parent link, never from the top of the ownership group. `null` when the record names no parent; the `legal_id` alone is absent when the parent record could not be resolved, and the name then falls back to the one stored inline on the link. - `site_type` (string, nullable): Whether this record is the company's headquarters: 'headquarters', 'branch', or 'unknown' when the datalake holds no value. Open vocabulary -- new values may be added, so treat this as a string, not a closed enum. - `vat` (string, nullable): The VAT identifier of the suggested entity, when the datalake has one. - `suggestions` (array of LegalIDSuggestion): Suggestions for the legal ID. Fields as in `match`. **Envelope:** `status_code` `200` means the job succeeded and `result` is populated; `202` means it is still running and `result` is `null`. A failed job comes back with `status` `"ERROR"`, its `status_code`, a stable `code` naming the cause and a `message` explaining it; an unknown or expired `job_id` is answered as a tool error. **Polling:** the MCP server holds this call and re-polls the job internally for up to ~25 seconds (this validation typically completes in ~5-10 seconds), so one call usually returns the final result. If `status_code` is still `202` after that, the job is still running and this tool accepts the same job id again. Re-reading a result never re-runs or re-charges the job. **Cost:** no new charge. Reading a result finalizes the job's accounting once: it settles the charge made at submission when the result is first delivered, or refunds it when the job failed, exceeded its time limit or produced no usable result, and marks a timed-out job failed. A repeat returns the same answer and never charges again.

getLegalIDResult