***

title: Enrich vendors with the API
subtitle: Use the API to enrich vendors with payment acceptance info and contact information
description: Integrate AI-powered vendor enrichment into your application. Scan invoices, search the web, and populate vendor payment details through the Payabli API
og:description: Integrate AI-powered vendor enrichment into your application. Scan invoices, search the web, and populate vendor payment details through the Payabli API
keywords: embedded payments, vendor enrichment, payment API, invoice scanning, vendor payments, REST API, payment acceptance, payables automation
icon: code
slug: guides/pay-out-developer-vendor-enrichment-integrate
---------------------

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

This guide covers how to integrate vendor enrichment into your application using the Payabli API. For background on how enrichment works, see [Vendor enrichment](/guides/pay-out-vendor-enrichment-overview).

<Note>
  Vendor enrichment is an opt-in feature. Contact Payabli to enable it for your organization.
</Note>

## Prerequisites

* Vendor enrichment enabled for your organization (contact Payabli)
* A valid API token with vendor permissions
* At least one active vendor to enrich

## Enrich an existing vendor

Use the [enrich vendor](/api-reference/pay-out/vendor/enrich-vendor) endpoint to run enrichment stages on a vendor that already exists.

### Request

Specify the `vendorId` and which stages to run in `scope`. Include a Base64-encoded PDF in `invoiceFile` when using the `invoice_scan` scope.

<EndpointRequestSnippet endpoint="POST /Vendor/enrich/{entry}" example="InvoiceScanReviewMode" />

### Response

The response includes the enrichment status and, when `applyEnrichmentData` is `false`, the raw extraction results.

<EndpointResponseSnippet endpoint="POST /Vendor/enrich/{entry}" example="InvoiceScanReviewMode" />

When `applyEnrichmentData` is `true`, the extracted data is written to the vendor record and also returned in the response.

<EndpointResponseSnippet endpoint="POST /Vendor/enrich/{entry}" example="WebSearchAutoApply" />

### Response status values

| Status                   | Meaning                                                                                   |
| ------------------------ | ----------------------------------------------------------------------------------------- |
| `completed`              | Enrichment finished and the vendor is payout-ready.                                       |
| `completed_from_network` | The vendor was already enriched in Payabli's vendor network. No AI processing was needed. |
| `insufficient`           | All requested stages ran but the vendor still lacks sufficient payment data.              |

### Handling the response

After receiving enrichment results in review mode (`applyEnrichmentData: false`):

1. Display the extracted data from `enrichmentData` to the user for confirmation.
2. Apply selected fields to the vendor with the [update vendor](/api-reference/pay-out/vendor/update-vendor) endpoint.

Check `stagesTriggered` to confirm which stages succeeded. Failed stages are excluded from this array.

## Scan an invoice during vendor creation

Attach a PDF invoice to the [create vendor](/api-reference/pay-out/vendor/create-vendor) request using the `attachment` field. When enrichment is enabled, the invoice is scanned and extracted details are merged into the vendor record.

```bash
curl -X POST 'https://api-sandbox.payabli.com/api/Vendor/single/$ENTRY_POINT' \
  -H 'Content-Type: application/json' \
  -H 'requestToken: $API_TOKEN' \
  -d '{
    "name1": "Acme Supplies",
    "attachment": {
      "ftype": "pdf",
      "filename": "invoice-101.pdf",
      "fContent": "<base64-encoded-pdf>"
    }
  }'
```

The merge follows the **empty-field-only rule**: request body fields always take precedence over extracted data. If you include `name1` in the request and the invoice scan also extracts a vendor name, your value wins.

If the scan fails for any reason, vendor creation proceeds with the original request data. The scan never causes vendor creation to fail.

## Scan an invoice during bill creation

The [create bill](/api-reference/pay-out/bill/add-bill) endpoint triggers an invoice scan when the first item in the `attachments` array is a PDF. No new request fields are needed — use the existing attachments array.

```bash
curl -X POST 'https://api-sandbox.payabli.com/api/Bill/single/$ENTRY_POINT' \
  -H 'Content-Type: application/json' \
  -H 'requestToken: $API_TOKEN' \
  -d '{
    "billNumber": "INV-2026-001",
    "netAmount": 1500.00,
    "attachments": [
      {
        "ftype": "pdf",
        "filename": "invoice-2026-001.pdf",
        "fContent": "<base64-encoded-pdf>"
      }
    ],
    "vendor": {
      "name1": "Acme Supplies"
    }
  }'
```

When the scan succeeds, the system:

1. Extracts vendor contact information and creates or matches a vendor using the extracted name and address.
2. Populates bill fields like invoice number, amount due, and due date from the scan results (empty-field-only).
3. Attaches the vendor to the bill.

The same empty-field-only rule applies — your request values always take precedence.

## Read enrichment status

The [get vendor](/api-reference/pay-out/vendor/get-vendor) endpoint returns enrichment fields directly on the vendor response:

<EndpointResponseSnippet endpoint="GET /Vendor/{idVendor}" example="GetVendor" />

Key fields:

| Field              | Description                                                                                              |
| ------------------ | -------------------------------------------------------------------------------------------------------- |
| `EnrichmentStatus` | Current enrichment state: `not_enriched`, `partially_enriched`, `fully_enriched`, or `fallback_applied`. |
| `EnrichedBy`       | Which method resolved the vendor's payment acceptance info.                                              |
| `PaymentPortalUrl` | URL for the vendor's online payment portal, if known.                                                    |
| `CardAccepted`     | Whether the vendor accepts card payments: `yes`, `no`, or `unable to determine`.                         |
| `AchAccepted`      | Whether the vendor accepts ACH payments: `yes`, `no`, or `unable to determine`.                          |

## Error handling

The enrich endpoint returns specific error messages when enrichment can't proceed:

| Condition                      | Message                                                               |
| ------------------------------ | --------------------------------------------------------------------- |
| Feature not enabled            | Vendor enrichment isn't enabled for this organization.                |
| Vendor not found or inactive   | Vendor not found or isn't active.                                     |
| Vendor doesn't belong to entry | Vendor doesn't belong to this entrypoint.                             |
| Enrichment already in progress | An enrichment request is already in progress for this vendor.         |
| Missing invoice file           | An invoice file is required when `invoice_scan` is included in scope. |

For invoice scans during vendor or bill creation, scan failures don't block the request. The creation request always succeeds, even if the scan fails.

## Related resources

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

<AccordionGroup>
  <Accordion title="Prerequisites">
    * **[Manage vendors with the API](/guides/pay-out-developer-vendors-manage)** - You need to understand vendor records before enriching them
  </Accordion>

  <Accordion title="Related topics">
    * **[Vendor enrichment](/guides/pay-out-vendor-enrichment-overview)** - Automate vendor payment research with AI-powered enrichment
    * **[Manage bills with the API](/guides/pay-out-developer-bills-manage)** - Learn how to add and manage bills for vendors via the API
  </Accordion>
</AccordionGroup>