Findymail

Remove excluded domains via DELETE /api/intellimatch/domains. Removes one or more domains from the user's exclusion lists. Only domains the user has permission to delete will be removed. For domains in shared lists, the user must have removeDomains permission on the list. For global domains (no list), the user must own the domain. THE TARGETS ARE IN THE BODY, NOT THE PATH: `ids` is the array of excluded-domain ids (from List excluded domains), and it is required. Domains you lack permission to remove are silently skipped rather than refused. Only the record's OWNER may change or delete it: a 403 {"message":"This action is unauthorized."} on a list or monitor shared with you by a teammate is Findymail enforcing ownership, not a credential failure. Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Delete an exclusion list via DELETE /api/intellimatch/exclusion-lists/{excludedDomainList_id}. Deletes an exclusion list and all its associated domains. Only the list owner can delete the list. Deletes the list AND every domain in it; the spec documents no restore. Answers 200 `{"success":true}`. Only the record's OWNER may change or delete it: a 403 {"message":"This action is unauthorized."} on a list or monitor shared with you by a teammate is Findymail enforcing ownership, not a credential failure. An id this account cannot see answers 404 {"message":"No query results for model [...] <id>"} naming the model -- a record that was deleted, never existed, or belongs to a team you are not on all answer identically. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Delete a contact list via DELETE /api/lists/{id}. Deletes the contact list; the spec documents no recycle bin and no restore. Answers 200 `{}` on success. An id this account cannot see answers 404 {"message":"No query results for model [...] <id>"} naming the model -- a record that was deleted, never existed, or belongs to a team you are not on all answer identically. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Delete a signal monitor via DELETE /api/signals/monitors/{id}. Soft-deletes the specified monitor. A SOFT delete per the spec: the monitor stops and disappears from lists; Findymail documents no restore endpoint. Answers 204 with no body. Only the record's OWNER may change or delete it: a 403 {"message":"This action is unauthorized."} on a list or monitor shared with you by a teammate is Findymail enforcing ownership, not a credential failure. An id this account cannot see answers 404 {"message":"No query results for model [...] <id>"} naming the model -- a record that was deleted, never existed, or belongs to a team you are not on all answer identically. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Get the contacts saved in a list via GET /api/contacts/get/{id}. `id` is a contact-list id from List contact lists, or 0 for every saved contact regardless of list. The reply is a DataTables-shaped document -- `draw`, `recordsTotal`, `recordsFiltered` and `data[]` with `id`, `name`, `email`, `linkedin_url`, `company`, `job_title`. The sealed spec types it text/plain, but measured 2026-09-19 on a freshly created empty list it is application/json: `{"draw":0,"recordsTotal":100000,"recordsFiltered":100000,"data":[],"disableOrdering":false}` -- note that `recordsTotal` read 100000 on a list holding NO contacts, so count `data`, not `recordsTotal`. An unknown list id answers 404 naming `Contacts\Models\LeadList`. An id this account cannot see answers 404 {"message":"No query results for model [...] <id>"} naming the model -- a record that was deleted, never existed, or belongs to a team you are not on all answer identically. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Get remaining credits via GET /api/credits. Two pools: `credits` (finder credits, spent by the finder, phone, company, lookalike, Intellimatch and technology-lookup tools) and `verifier_credits` (spent by Verify an email address). Measured 2026-09-19 on this account: {"credits":25,"verifier_credits":10} -- the reply also carries the account `email`, `id` and `pricing` variant. Call this before a batch of metered searches to know what the batch can afford. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Get credit usage over time via GET /api/credits/report/summary. Returns the daily or monthly credit usage of the authenticated user. Groups by day for periods shorter than 2 months, otherwise groups by month. `from` and `to` are YYYY-MM-DD (measured: anything else -> 422 'must be a valid date'); `from` defaults to 30 days ago and `to` to today. The reply is `total.finder`/`total.verifier` plus `items[]` per day, or per month for spans of two months or more. A `from` after `to` is not refused -- it answers 200 with empty `items`. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Get credit usage by team member via GET /api/credits/report/team-summary. Returns a summary of credit usage of all team members within a specific date range. Only team owners can access this endpoint. Team OWNERS only: anyone else answers 403 {"error":"You must be the team owner to access this endpoint"}, which is a role, not a bad token. Same `from`/`to` rules as Get credit usage over time; the reply lists `members[]` with each person's finder and verifier spend. Measured 2026-09-19: 200 with the one member of this account's team. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Get an Intellimatch search's results via GET /api/intellimatch/data. Retrieve paginated company and contact results from a completed search task. Only for a search whose status is `success`; measured 2026-09-19, an unknown hash answers 404 {"status":"error","message":"Failed to retrieve data. Please try again."}. `per_page` defaults to 100 and is capped at 500 (501 -> 422). Each row is a company with its match score and, when contacts were requested, the contact's name, email, job title, phone and profile URL. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

List excluded domains via GET /api/intellimatch/domains. Returns a paginated list of excluded domains for the authenticated user. Can be filtered by list_id to get domains from a specific list, otherwise returns the global exclusion list. Without `list_id` this is the account's GLOBAL exclusion list (domains added with no list). The envelope is Laravel's paginator -- `data[]`, `current_page`, `per_page`, `total`, `last_page`, `next_page_url` -- and each row is `{id, domain, excluded_domain_list_id}`; the `id` here is what Remove excluded domains takes. `per_page` is capped at 100 (measured: 100000 -> 422 'must not be greater than 100'); the default is 15. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

List exclusion lists via GET /api/intellimatch/exclusion-lists. Returns all exclusion lists the authenticated user has access to (owned lists and lists shared with their team) Exclusion lists hold the domains an Intellimatch or lookalike search must skip (competitors, existing customers). Each row carries `id`, `name`, `is_shared`, `is_owner`, `user_id` and `owner_name`. This is also this integration's connection probe: measured 2026-09-19, the real token -> 200 `{"lists":[]}` (then the one list this build created, with its `id`, `is_owner` true, `owner_name`); a bogus token, no Authorization header, and the token sent WITHOUT the `Bearer` prefix -> 401 {"message":"Unauthenticated."}. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Get an exclusion list via GET /api/intellimatch/exclusion-lists/{excludedDomainList_id}. Returns the details of a specific exclusion list (without domains). To get domains, use the dedicated GET /api/intellimatch/domains?list_id={id} endpoint. Users can only access lists they own or lists shared with their team. The list's metadata only, WITHOUT its domains -- read those with List excluded domains filtered by `list_id`. Measured 2026-09-19 on the list this build created: 200 with the same `id`, `name`, `is_shared`, `is_owner`, `user_id` and `owner_name` the create returned. An id this account cannot see answers 404 {"message":"No query results for model [...] <id>"} naming the model -- a record that was deleted, never existed, or belongs to a team you are not on all answer identically. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Get an Intellimatch search's status via GET /api/intellimatch/status. Poll this endpoint to check if a given search is completed. The response will contain a `status` field with one of the following values: - `success`: Export is completed and ready to download - `processing`: Export is currently being processed (includes progress information) - `pending`: Export is queued but not yet started - `failed`: Export has failed - `not_found`: Export hash not found or expired Measured 2026-09-19: a hash no search produced answers 200 {"status":"not_found"} rather than 404, so read the `status` field -- `success`, `processing` (with `progress` and job counts), `pending`, `failed` or `not_found` -- and never the HTTP code alone. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

List contact lists via GET /api/lists. Returns the contact (lead) lists this token can see -- the ones the account owns plus the ones teammates shared -- each with `id`, `name`, `shared_with_team` and `is_owner`. This is where a list id comes from for the other list tools and for `lead_list_id` on searches and monitors. Measured 2026-09-19: `{"lists":[]}` on the fresh account, then the one list created by this build's write pass appeared here with the same `id` the create returned. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

List signals via GET /api/signals. Returns a paginated list of signals from monitors accessible by the authenticated user (owned and team-shared). Supports filtering by signal_type, monitor_id, and date range. Signals are the events the account's monitors detected -- keyword mentions, new hires, job changes, post engagement -- each with its contact, company, `detected_at`, `expires_at` and the monitors that matched it. `signal_type` is one of `keyword_mention`, `new_hire`, `job_change`, `post_engagement`; `relevance_scores` is a comma-separated subset of 0-5 (anything else -> 422); dates are YYYY-MM-DD. `per_page` defaults to 50 and is CLAMPED to 100 rather than refused (measured: 101 -> 100). The Signals feature can be disabled on a plan, which Findymail reports as 404 with an empty body rather than as a permission error. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Get a signal via GET /api/signals/{id}. Returns a single signal with its associated contact, company, and the authenticated user's monitors. One signal with its contact, company and the monitors that matched it. An id this account cannot see answers 404 naming `Signals\Models\Signal` (measured 2026-09-19). An id this account cannot see answers 404 {"message":"No query results for model [...] <id>"} naming the model -- a record that was deleted, never existed, or belongs to a team you are not on all answer identically. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

List signal monitors via GET /api/signals/monitors. Returns all monitors accessible by the authenticated user (owned and team-shared), ordered by most recent first. Each monitor includes a match_count with the number of signals matched. Every monitor this token can see, newest first, each with its `signal_type`, `status`, `keywords`, `icp_filters`, `webhook_url`, `match_count`, `is_shared` and `is_owner`. `ownership` is `my`, `team` or `all` (measured: anything else -> 422 'The selected ownership is invalid.'). Measured 2026-09-19 on this account: `[]`. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Search the technology catalog via GET /api/technologies/search. Search the technology catalog by name. Returns up to 25 technologies. Free endpoint — no credits consumed. Rate-limited to 10 requests per minute. The names to pass as `technologies` to Look up a company's technology stack. `q` is required and at least 2 characters (measured: `R` -> 422). Each row is `{name, category, subcategory}`; measured 2026-09-19, `q=React` returned React, React Native, react-testing-library and more. THIS ROUTE HAS ITS OWN RATE LIMIT of 10 requests per minute (x-ratelimit-limit: 10, measured), against 5000 elsewhere. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Update a signal monitor via PATCH /api/signals/monitors/{id}. Updates an existing monitor. The signal_type cannot be changed after creation. A PATCH: send only the fields to change. `signal_type` CANNOT be changed after creation; `target_companies` is refused (422) unless the type is `new_hire` or `job_change`; only the owner or a team admin may change `is_shared`. Only the record's OWNER may change or delete it: a 403 {"message":"This action is unauthorized."} on a list or monitor shared with you by a teammate is Findymail enforcing ownership, not a credential failure. An id this account cannot see answers 404 {"message":"No query results for model [...] <id>"} naming the model -- a record that was deleted, never existed, or belongs to a team you are not on all answer identically. Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Add excluded domains via POST /api/intellimatch/domains. Adds one or more domains to the user's exclusion list. If list_id is provided, domains are added to that specific list. For large batches (>50 domains), the first 50 are processed immediately and the rest are queued for background processing. `domains` is required (measured: `{}` -> 422 'The domains field is required.'), up to 10000 names per call; beyond 50 the rest are queued and the reply reports `processed_immediately` and `queued` counts. Without `list_id` the domains become global exclusions. Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Create an exclusion list via POST /api/intellimatch/exclusion-lists. Creates a new exclusion list for the authenticated user. Optionally share the list with the user's current team. `name` is required and must be unique per user; `is_shared` requires the account to be on a team. Measured 2026-09-19: `{}` -> 422 'The name field is required.'; a valid name -> 200 with the list (`id`, `name`, `is_shared` false, `is_owner` true, `user_id`, `owner_name`), readable at once at its own address; the SAME name again -> 422 'The name has already been taken.' Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Start an Intellimatch lead search via POST /api/intellimatch/search. Create an Intellimatch search task. Intellimatch is Findymail's intelligent company search tool that lets you build highly targeted lead lists using plain language queries. Instead of manually applying filters or reviewing websites one by one, Intellimatch uses real-time semantic search to find the best-fit companies and contacts. The API responds immediately with a `hash` identifying the task for polling completion status. Please check https://help.findymail.com/en/article/what-is-supported-in-intellimatch-15s0u10/ for more information about what is supported or not. `query` is plain language ("SaaS companies in US with 50-200 employees"); `limit` defaults to 100 and maxes at 5000. The reply is only `{"hash": ...}` -- the search runs asynchronously, so poll Get an Intellimatch search's status with that hash until `status` is `success`, then read Get an Intellimatch search's results. `config.target_job_titles` is up to 3 priority tiers, each a list of equivalent titles. Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. COSTS FINDER CREDITS according to `config`: 1 per email found when `find_email` is true and 10 per phone number found when `find_phone` is true; with `require_email` true, companies without an email are excluded and not charged. The search runs asynchronously and charges as it enriches, so a `limit` of 5000 with `find_email` on is a 5000-credit exposure. A 402 here means the account is OUT OF CREDITS and a 423 means the Findymail SUBSCRIPTION IS PAUSED -- neither is a bad token, and neither is fixed by reconnecting; top up or resume the plan at app.findymail.com. Only a 401 {"message":"Unauthenticated."} is a credential problem. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Create a contact list via POST /api/lists. `name` is required (measured: `{}` -> 422 'The name field is required.'). The new list is returned under `list` with its `id`, `created_at`, `shared_with_team` (false) and `is_owner` (true) -- measured 2026-09-19 with a disposable list, which then appeared in List contact lists and answered Get the contacts saved in a list. Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Search lookalike companies via POST /api/lookalike/search. Find companies similar to a given seed domain. Optionally filter results by same country or same company size, and exclude companies from specific exclusion lists. Credit cost: 1 Finder credit per 10 results returned (rounded up). `seed` (a company domain or URL) is required; `limit` defaults to 100 and maxes at 10000; `exclusion_list_ids` drops companies already in those exclusion lists. Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. COSTS 1 FINDER CREDIT PER 10 RESULTS RETURNED, rounded up -- so `limit` is the budget knob, and the default of 100 results costs 10 credits. A 402 here means the account is OUT OF CREDITS and a 423 means the Findymail SUBSCRIPTION IS PAUSED -- neither is a bad token, and neither is fixed by reconnecting; top up or resume the plan at app.findymail.com. Only a 401 {"message":"Unauthenticated."} is a credential problem. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Find an email from a business profile URL via POST /api/search/business-profile. Find someone's email from a business profile URL. Uses one finder credit if a verified email is found. This endpoint is limited to 30 concurrent requests (when used synchronously) `linkedin_url` accepts the full profile URL or the bare username. The spec limits this route to 30 concurrent synchronous requests. If `webhook_url` is supplied the search runs in the background and the result is POSTed to that URL instead of being returned here -- the synchronous reply then carries no contact, so omit `webhook_url` when the answer is wanted in this call. Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. COSTS 1 FINDER CREDIT if a verified email is found; a search that finds nothing is free. A 402 here means the account is OUT OF CREDITS and a 423 means the Findymail SUBSCRIPTION IS PAUSED -- neither is a bad token, and neither is fixed by reconnecting; top up or resume the plan at app.findymail.com. Only a 401 {"message":"Unauthenticated."} is a credential problem. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Get company information via POST /api/search/company. Retrieve company data using a company profile URL, name, or website domain. At least one of these fields must be specified. Consumes 1 Finder credit per successful response (only when company data is found). Supply at least ONE of `linkedin_url`, `domain` or `name` -- none is individually required, but all three absent answers 422 {"error":"One identifier is required: linkedin_url, domain, name"}, and no match answers 404 {"message":"Not Found"}. The reply carries name, domain, company_size, industry, linkedin_url and description. Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. COSTS 1 FINDER CREDIT per successful response -- only when company data is found; a 404 is free. A 402 here means the account is OUT OF CREDITS and a 423 means the Findymail SUBSCRIPTION IS PAUSED -- neither is a bad token, and neither is fixed by reconnecting; top up or resume the plan at app.findymail.com. Only a 401 {"message":"Unauthenticated."} is a credential problem. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Find contacts at a domain by role (deprecated) via POST /api/search/domain. Try finding a contact with a valid email at a given domain with a given role. A contact is only returned if we found a valid email. Due to the heavy processing involved (real-time search), this endpoint is limited to 5 concurrent requests (when used synchronously) and async jobs can take up to 24 hours to be processed depending on our workload (usually sooner). `roles` takes at most 3 target roles. Real-time search: the spec limits this route to 5 concurrent synchronous requests, and with `webhook_url` the job may take up to 24 hours. DEPRECATED BY FINDYMAIL: its own documentation says this endpoint 'is no longer recommended for production usage' and points at Find employees at a company (findymail_post_api_search_employees) instead. It still answers, but prefer the replacement for new work. If `webhook_url` is supplied the search runs in the background and the result is POSTed to that URL instead of being returned here -- the synchronous reply then carries no contact, so omit `webhook_url` when the answer is wanted in this call. Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. COSTS FINDER CREDITS for the contacts it returns (the spec states no per-contact figure for this route; budget 1 per contact as the Find employees tool charges). A 402 here means the account is OUT OF CREDITS and a 423 means the Findymail SUBSCRIPTION IS PAUSED -- neither is a bad token, and neither is fixed by reconnecting; top up or resume the plan at app.findymail.com. Only a 401 {"message":"Unauthenticated."} is a credential problem. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Find employees at a company via POST /api/search/employees. Find one or more employees using the company website and job title. This endpoint uses 1 credit per found contact. This endpoint does NOT return an email. `website` and `job_titles` (up to 10) are required; `count` is how many contacts to return (default 1, max 5). Each result carries `name`, `linkedinUrl`, `companyWebsite`, `companyName` and `jobTitle` -- and NO email, by design. Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. COSTS 1 FINDER CREDIT PER CONTACT FOUND (up to `count`, max 5), and returns NO email address -- pair it with Find an email from a business profile URL, which costs another credit per verified email. A 402 here means the account is OUT OF CREDITS and a 423 means the Findymail SUBSCRIPTION IS PAUSED -- neither is a bad token, and neither is fixed by reconnecting; top up or resume the plan at app.findymail.com. Only a 401 {"message":"Unauthenticated."} is a credential problem. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Find an email from a name and company via POST /api/search/name. Find someone's email from name and company (website or name). Uses one finder credit if a verified email is found. `name` (the person's full name) and `domain` (the company website, or its name as a fallback) are both required. The reply carries the contact with its verified email, or no contact when none was found. If `webhook_url` is supplied the search runs in the background and the result is POSTed to that URL instead of being returned here -- the synchronous reply then carries no contact, so omit `webhook_url` when the answer is wanted in this call. Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. COSTS 1 FINDER CREDIT if a verified email is found; a search that finds nothing is free. A 402 here means the account is OUT OF CREDITS and a 423 means the Findymail SUBSCRIPTION IS PAUSED -- neither is a bad token, and neither is fixed by reconnecting; top up or resume the plan at app.findymail.com. Only a 401 {"message":"Unauthenticated."} is a credential problem. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Find a phone number from a business profile URL via POST /api/search/phone. Find someone's phone number from a business profile URL. Uses 10 finder credits if a phone is found. For legal reasons, requests for EU citizens will not return any result. `linkedin_url` accepts the full profile URL or the bare username. Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. COSTS 10 FINDER CREDITS if a phone number is found -- ten times the price of an email -- and for legal reasons returns nothing for EU citizens, which is then free. A 402 here means the account is OUT OF CREDITS and a 423 means the Findymail SUBSCRIPTION IS PAUSED -- neither is a bad token, and neither is fixed by reconnecting; top up or resume the plan at app.findymail.com. Only a 401 {"message":"Unauthenticated."} is a credential problem. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Reverse-look up an email address via POST /api/search/reverse-email. Find a business profile from an email address (work email or personal email). Credit usage: - Uses 1 finder credit if a profile is found (without profile data) - Uses 2 finder credits if a profile is found with complete profile data (only if `with_profile` option enabled) Works on work AND personal addresses; `with_profile` adds the profile metadata at the higher price. Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. COSTS 1 FINDER CREDIT if a profile is found, or 2 when `with_profile` is true and complete profile data is returned; nothing found is free. A 402 here means the account is OUT OF CREDITS and a 423 means the Findymail SUBSCRIPTION IS PAUSED -- neither is a bad token, and neither is fixed by reconnecting; top up or resume the plan at app.findymail.com. Only a 401 {"message":"Unauthenticated."} is a credential problem. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Create a signal monitor via POST /api/signals/monitors. Creates a new signal monitor for the authenticated user. `name` and `signal_type` are required (measured: `{}` -> 422 naming both); the other fields depend on the type -- `keywords` (max 5) for `keyword_mention`, `post_url` or `profile_url` plus `engagement_types` (`like`, `comment`) for `post_engagement`, and `target_companies` only for `new_hire` and `job_change` (422 on any other type). `webhook_url` must be HTTPS. A monitor with `enrichment_level` set spends finder credits as it enriches the contacts it matches -- a standing cost, not a one-off. Answers 201 with the monitor. Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Look up a company's technology stack via POST /api/technologies. Get the technology stack for a company by its domain. Optionally filter by technology name (case-insensitive). Credit cost: 1 Finder credit when technologies are found. Free when no results. `domain` is required; `technologies` narrows the reply to the named stacks, case-insensitively. Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. COSTS 1 FINDER CREDIT when technologies are found; free when nothing is found. A 402 here means the account is OUT OF CREDITS and a 423 means the Findymail SUBSCRIPTION IS PAUSED -- neither is a bad token, and neither is fixed by reconnecting; top up or resume the plan at app.findymail.com. Only a 401 {"message":"Unauthenticated."} is a credential problem. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Verify an email address via POST /api/verify. Uses one verifier credit on all attempted verification The reply is `{"email", "verified", "provider"}`; the sealed spec types it text/plain, so the connector returns whatever document Findymail sends rather than assuming JSON. Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. COSTS 1 VERIFIER CREDIT on every attempted verification, whether or not the address turns out to be valid -- this is the one tool billed per attempt rather than per result. A 402 here means the account is OUT OF CREDITS and a 423 means the Findymail SUBSCRIPTION IS PAUSED -- neither is a bad token, and neither is fixed by reconnecting; top up or resume the plan at app.findymail.com. Only a 401 {"message":"Unauthenticated."} is a credential problem. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Update an exclusion list via PUT /api/intellimatch/exclusion-lists/{excludedDomainList_id}. Updates an exclusion list's name and/or sharing status. Only the list owner can update or change sharing settings. `name` is required on every call even when only `is_shared` changes. Sharing needs a team: 400 {"error":"You must be part of a team to share lists."} otherwise. Only the record's OWNER may change or delete it: a 403 {"message":"This action is unauthorized."} on a list or monitor shared with you by a teammate is Findymail enforcing ownership, not a credential failure. An id this account cannot see answers 404 {"message":"No query results for model [...] <id>"} naming the model -- a record that was deleted, never existed, or belongs to a team you are not on all answer identically. Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.

Update a contact list via PUT /api/lists/{id}. BOTH `name` and `isShared` are required on every call -- this replaces the two settable fields rather than patching one, so read the list first and resend the name you are not changing. Note the camelCase `isShared` on this route against `is_shared` everywhere else in the API. An id this account cannot see answers 404 {"message":"No query results for model [...] <id>"} naming the model -- a record that was deleted, never existed, or belongs to a team you are not on all answer identically. Findymail validates the body BEFORE acting and answers 422 with a per-field `errors` object naming exactly what is missing or malformed, so a 422 creates and changes nothing. Consumes NO credits: Findymail meters only its finder, verifier and lookup routes, and this is an account, list, exclusion-list, signal or usage operation. Findymail allows 5000 requests per minute per token (the technology catalog search has its own budget of 10 per minute) and caps concurrency at 300 simultaneous requests; a 429 {"message":"Too Many Attempts."} is the budget, never the credential, and a rejected credential consumes none of it.