Skip to main content
A Plyne source chain runs sources one at a time in the order you choose. Execution stops when a source returns usable data or a pending operation. You control whether an error or an empty result allows the next source to run.

Default, one source or a chain

Omit routing to use the tool’s default eligible sources. Describe the tool and call its free /plan endpoint to inspect the available choices for your request. Default execution can also use a capability’s existing cache or identity-resolution behavior; it is not a promise that every listed source will run. For an explicit chain, put the source IDs in routing.providers. One entry runs only that source. This company profile example selects Fetchin followed by Harvest:
Submit the body to /v1/tools/company_profile/plan before /execute. Both sources must be configured and support the request. The example illustrates chain selection, not a guarantee that either source will return a profile.

How a chain runs

Plyne checks the request before acquisition. With a valid explicit chain, it calls the first source and evaluates its result. An enabled fallback condition advances to the next source, if one remains. By default, a later usable result does not include or merge the earlier source’s results. Profile field completion is an explicit exception described below.
The walkthrough uses simulated outcomes and generic source labels. It sends no request and spends no credits. It illustrates the shared chain behavior, not an account’s live source availability.
If all attempted sources are empty, the operation can return not_found. If a chain cannot produce usable data after a failed attempt, it can return failed. Inspect the tool’s status, error and routing trace instead of treating every HTTP 200 as successful acquisition.

Choose fallback conditions

fallback_on accepts error, empty, or both. If you omit it from a multi-source chain, both conditions are enabled. An empty array does not disable fallback; use a one-entry chain to select only one source. A chain does not query every source for comparison or fill a short page from another source. Use separate operations with new keys if you intentionally want independent results from multiple sources.

Keep filter meanings intact

Every selected source must preserve your requested filters. For example, title-only matching and a keyword search across title and description are different operations. Plyne rejects an incompatible explicit chain rather than silently dropping a filter. Nonempty provider_options select their matching source alone. Read the tool’s published schema for the accepted namespace and fields. Source IDs and option namespaces can be platform names such as x, reddit or crunchbase; these identify the public data source, not its underlying transport.

Read the routing trace

The response’s routing metadata reports the mode, attempted sources and their outcomes, and the selected source where applicable. A selected source is not by itself proof of usable data: inspect status and data as well. For paginated tools, continue with the source and continuation fields returned by that tool. Keep the filters and page size unchanged. Do not switch sources in the middle of a result set. See tool execution and credits and recovery.

Complete profile fields

For company_profile and person_profile, set required_fields to the top-level output fields you need. Omission preserves the existing resolver and fallback behavior. With this option, the default eligible source chain—or your explicit routing.providers chain—continues after a usable but incomplete profile. Execution stops as soon as every requested field is present. Errors and empty results follow routing.fallback_on; a pending operation pauses the chain.
Sources must identify the same entity through shared LinkedIn or domain anchors. Conflicting identities are rejected. The first populated value is retained; subsequent sources fill missing fields. Employment objects and headcount bundles are not assembled from incompatible pieces. The response includes fulfillment.satisfied, fulfillment.missing_fields and fulfillment.field_sources. Exhausting the chain with usable but incomplete data returns partial. An empty array or unknown field is not a supported requirement in the public schema. This is field availability, not an accuracy guarantee. The request retains the tool’s quoted request price; source attempts do not create separate customer requests. Inspect usage for the final charge. API and MCP use the same contract.

Find and validate work email

work_email finds an address through FullEnrich and applies the shared email validation policy. A native valid status avoids an extra validation call; other statuses are checked with ZeroBounce. This is a find-and-validate pipeline, not a chain of interchangeable finding sources. Set verification: "verified" to accept only a valid address. Set verification: "allow_catch_all" to also accept catch-all addresses, which remain unverified. Omitting the option preserves catch-all acceptance. No acceptable address returns not_found; a validation failure returns an error rather than an unchecked address. Returned addresses include verification.status, verification.provider and verification.checked_at. An explicit requirement also returns fulfillment. Poll or replay the same request to retrieve the result without starting another finding job.

Additional fields

Company and person profiles, job search, job details and supported social tools automatically return reviewed additional fields without extra provider calls. The common record keeps its normal shape; documented source business fields appear in data.additional_fields, grouped by source. Only values already preserved in the common record are removed as duplicates. For example, if the common id is 123 and a source also returns shareUrn: "urn:li:share:456", the different URN remains in additional_fields. Structured source fields can remain intact when their shape differs from the common schema. Unknown fields, provider billing and transport envelopes are excluded. This option does not run extra provider calls or turn profile enrichment into an email or phone lookup. Use each tool’s published output schema to see its supported fields.

Response size

Responses support up to 4 MiB. If additional fields make a response exceed this limit, they are omitted and warnings includes additional_fields_omitted. Common records, source evidence and pagination remain available, with the usual billing policy. If the common response alone is too large, the request fails with result_too_large and is not charged. Replaying the same key returns the saved response without another source call.