> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md

# Vendor enrichment

> Automate vendor payment research with AI-powered enrichment

Vendor enrichment uses AI to gather vendor payment acceptance info and contact information, reducing the manual research needed to pay vendors using the payment methods they accept. The enrichment pipeline progressively fills in vendor details through up to three stages: invoice scanning, web search, and an AI outreach call.

Vendor enrichment requires configuration by the Payabli team. Contact us to get started.

Vendor enrichment is a separate feature from the [OCR engine](/guides/pay-ops-developer-ocr-use): enrichment finds *which payment methods a vendor accepts* and their contact details, while OCR *extracts bill and invoice data* from a PDF or image.

## How enrichment works

When you trigger enrichment for a vendor, the system runs one or more stages based on the scope you request. Each stage attempts to find the vendor's contact information and what payment methods they accept.

### Invoice scanning

The invoice scan stage extracts vendor details from a PDF invoice, including:

* Vendor name, address, phone, and email
* Payment portal URLs
* Whether the vendor accepts cards, ACH, or checks
* Invoice number, amount due, and due date

### Web search

The web search stage searches official websites, business directories, and bill pay platforms to find:

* Phone numbers, emails, and addresses
* Payment portal URLs
* Whether the vendor accepts cards, ACH, or checks

### AI outreach calling

AI outreach calling is in beta and is opt-in. Contact your Payabli representative to enable it, provision a phone number for your merchants, and discuss pricing.

When invoice scanning and web search can't determine how a vendor wants to be paid, Payabli can schedule an AI agent to call the vendor. The agent asks which payment methods the vendor accepts (card, ACH, or check) and collects a contact email. This is the third enrichment stage.

Outreach calling triggers in two ways:

* **Automatically**, as the third pipeline stage, when you set `scheduleCallIfNeeded` to `true` on the [enrich vendor](/developers/api-reference/vendor/enrich-vendor) request and the earlier stages return insufficient payment acceptance info.
* **Directly**, through the [schedule outreach call](/developers/api-reference/vendor/schedule-enrichment-call) endpoint.

#### Outreach behavior

* **Scheduling window.** Calls are placed on the next business day at around 9 AM in the vendor's timezone. The calling window is Monday through Friday, 9 AM to 6 PM in that timezone. Setting `sendNow` to `true` dispatches the call immediately and bypasses both the business-hours window and the due-date check.
* **Retries and fallback.** If the vendor doesn't answer, Payabli retries up to three times by default (configurable, maximum five). When all retries are exhausted, the fallback payment method is applied to the vendor record.
* **Due-date skip.** When a call is tied to a bill that's due in fewer than three days, the call is skipped and the fallback method is applied immediately.
* **Daily cap.** A per-organization daily call cap can defer a vendor's call to a later day.
* **Automated-system detection.** If the agent reaches an IVR menu, voicemail, or another automated system, it ends the call gracefully.

You can read the latest call activity for a vendor from the [get outreach call status](/developers/api-reference/vendor/get-enrichment-call-status) endpoint. It returns one of four states:

| State        | Meaning                                                 |
| ------------ | ------------------------------------------------------- |
| `none`       | No call activity for the vendor.                        |
| `scheduled`  | A call is queued or waiting to be retried.              |
| `successful` | A call completed and returned payment and contact data. |
| `failed`     | The call didn't complete successfully.                  |

### Stage ordering

When you request both the invoice scan and web search stages, invoice scan always runs first. If the vendor becomes payout-ready after the scan, web search is skipped. When both stages run, invoice scan results are passed to web search as context so it can skip redundant searches. If both stages run and the vendor still lacks payment acceptance info, the outreach call runs as the third stage when `scheduleCallIfNeeded` is set.

## Enrichment status

After enrichment, the vendor record includes status fields that reflect the current state. You can read these fields from the [get vendor](/developers/api-reference/vendor/get-vendor) endpoint.

| Status               | Meaning                                                                                                       |
| -------------------- | ------------------------------------------------------------------------------------------------------------- |
| `not_enriched`       | No enrichment has been attempted.                                                                             |
| `partially_enriched` | Some fields are populated, but the vendor doesn't yet have enough payment acceptance info to be payout-ready. |
| `fully_enriched`     | The vendor has all required payment acceptance info and is payout-ready.                                      |
| `fallback_applied`   | Enrichment retries exhausted and a fallback payment method was applied.                                       |

The `EnrichedBy` field indicates which method resolved the vendor's payment acceptance info: `invoice_scan`, `web_search`, `vendor_network` (inherited from an already-enriched vendor in Payabli's network), or `manual`.

## Ways to trigger enrichment

### Payabli Portal

You can enrich a vendor directly from the vendor record in the Payabli Portal. This is a single-click action that triggers the enrichment pipeline without any API integration.

### API

There are three ways to trigger enrichment through the API:

1. **Enrich an existing vendor** — Use the [enrich vendor](/developers/api-reference/vendor/enrich-vendor) endpoint to run invoice scan, web search, or both on a vendor that already exists.
2. **Upload an invoice during vendor creation** — Attach a PDF to the [create vendor](/developers/api-reference/vendor/create-vendor) request. The invoice is scanned and extracted details are merged into the vendor record.
3. **Upload an invoice during bill creation** — Attach a PDF to the [create bill](/developers/api-reference/bill/add-bill) request. The invoice is scanned and extracted details populate both the vendor and the bill.

For API implementation details, see [Enrich vendors with the API](/guides/pay-out-developer-vendor-enrichment-integrate).

## Apply modes

The enrich vendor endpoint supports two modes through the `applyEnrichmentData` parameter:

* **Automatic** (`true`, the default) — Extracted data is written directly to the vendor record. Only empty fields are populated and existing values are never overwritten. The extracted data is also returned in the response.
* **Review mode** (`false`) — Extracted data is returned in the response without modifying the vendor. Use this for UI flows where users review and confirm changes before applying them with the [update vendor](/developers/api-reference/vendor/update-vendor) endpoint.

In both modes, `enrichmentData` in the response contains the raw extraction results.

## Vendor network

Payabli maintains a network of vendors that have already been enriched. When you trigger enrichment, the system first checks whether the vendor already exists in this network. If a match is found, the vendor's payment acceptance info is populated immediately without running AI processing. In this case, the enrich endpoint returns a status of `completed_from_network`.

## Related resources

See these related resources to help you get the most out of Payabli.

#### Related topics

* **[Enrich vendors with the API](/guides/pay-out-developer-vendor-enrichment-integrate)** - Use the API to enrich vendors with payment acceptance info and contact information
* **[Manage vendors with the API](/guides/pay-out-developer-vendors-manage)** - Learn how to add and manage vendors with the Payabli API
* **[Manage vendors (Portal)](/guides/pay-out-portal-vendors-manage)** - Find, view, update, and remove your vendor records in the Payabli Portal to keep payout details current