Send paymentsVendor enrichment

Enrich vendors with the API

Use the API to enrich vendors with payment acceptance info and contact information
View as MarkdownOpen in Claude

This guide covers how to integrate vendor enrichment into your application using the Payabli API. For background on how enrichment works, see Vendor enrichment.

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

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 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.

POST
/api/Vendor/enrich/:entry
1curl -X POST https://api-sandbox.payabli.com/api/Vendor/enrich/8cfec329267 \
2     -H "requestToken: <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "vendorId": 3890,
6  "scope": [
7    "invoice_scan"
8  ],
9  "applyEnrichmentData": false,
10  "invoiceFile": {
11    "fContent": "<base64-encoded-pdf>",
12    "filename": "invoice-2026-001.pdf",
13    "ftype": "pdf"
14  },
15  "fallbackMethod": "check"
16}'
Try it

Response

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

Response
1{
2  "responseText": "Success",
3  "responseCode": 1,
4  "isSuccess": true,
5  "responseData": {
6    "enrichmentId": "enrich-3890-a1b2c3d4",
7    "status": "insufficient",
8    "stagesTriggered": [
9      "invoice_scan"
10    ],
11    "vendorPayoutReady": false,
12    "enrichmentData": {
13      "invoiceScan": {
14        "vendorName": "Greenfield Landscaping",
15        "street": "456 Commerce Blvd",
16        "city": "Indianapolis",
17        "state": "IN",
18        "zipCode": "46201",
19        "country": "US",
20        "phone": "5555550100",
21        "cardAccepted": "unable to determine",
22        "achAccepted": "unable to determine",
23        "checkAccepted": "yes",
24        "invoiceNumber": "INV-70683",
25        "amountDue": 390.5,
26        "dueDate": "2026-01-31"
27      }
28    }
29  }
30}

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

Response
1{
2  "responseText": "Success",
3  "responseCode": 1,
4  "isSuccess": true,
5  "responseData": {
6    "enrichmentId": "enrich-3891-c9d0e1f2",
7    "status": "completed",
8    "stagesTriggered": [
9      "web_search"
10    ],
11    "vendorPayoutReady": true,
12    "enrichmentData": {
13      "webSearch": {
14        "phone": "5555550200",
15        "phoneType": "main",
16        "email": "ap@greenfield-landscaping.com",
17        "emailType": "billing",
18        "street": "456 Commerce Blvd",
19        "city": "Indianapolis",
20        "state": "IN",
21        "zipCode": "46201",
22        "country": "US",
23        "addressType": "business",
24        "paymentLink": "https://greenfield-landscaping.com/pay",
25        "paymentLinkType": "payment_portal",
26        "cardAccepted": "yes",
27        "achAccepted": "unable to determine",
28        "checkAccepted": "yes"
29      }
30    }
31  }
32}

Response status values

StatusMeaning
completedEnrichment finished and the vendor is payout-ready.
completed_from_networkThe vendor was already enriched in Payabli’s vendor network. No AI processing was needed.
insufficientAll 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 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 request using the attachment field. When enrichment is enabled, the invoice is scanned and extracted details are merged into the vendor record.

$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 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.

$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 endpoint returns enrichment fields directly on the vendor response:

Response
1{
2  "Address1": "123 Ocean Drive",
3  "Address2": "Suite 400",
4  "BillingData": {
5    "id": 123456,
6    "nickname": "Main Checking Account",
7    "bankName": "Example Bank",
8    "routingAccount": "123456789",
9    "accountNumber": "9876543210",
10    "typeAccount": "Checking",
11    "bankAccountHolderName": "John Doe",
12    "bankAccountHolderType": "Business",
13    "bankAccountFunction": 2,
14    "verified": true,
15    "status": 1,
16    "services": [],
17    "default": true,
18    "accountId": "bank-account-001"
19  },
20  "City": "Bristol",
21  "Contacts": {
22    "ContactEmail": "eric@martinezcoatings.com",
23    "ContactName": "Eric Martinez",
24    "ContactPhone": "5555555555",
25    "ContactTitle": "Owner"
26  },
27  "Country": "US",
28  "CreatedDate": "2022-07-01T15:00:01Z",
29  "customerVendorAccount": "123-456",
30  "customField1": "",
31  "customField2": "",
32  "EIN": "123456789",
33  "Email": "example@email.com",
34  "externalPaypointID": "Paypoint-100",
35  "InternalReferenceId": 1000000,
36  "LastUpdated": "2022-07-01T15:00:01Z",
37  "LocationCode": "LOC123",
38  "Mcc": "7777",
39  "Name1": "Herman's Coatings",
40  "Name2": "Herman's Coating Supply Company, LLC",
41  "ParentOrgName": "PropertyManager Pro",
42  "ParentOrgId": 1000,
43  "payeeName1": "payeeName1",
44  "payeeName2": "payeeName2",
45  "PaypointDbaname": "Sunshine Gutters",
46  "PaypointEntryname": "d193cf9a46",
47  "PaypointLegalname": "Sunshine Services, LLC",
48  "Phone": "2125551234",
49  "remitAddress1": "123 Walnut Street",
50  "remitAddress2": "Suite 900",
51  "remitCity": "Miami",
52  "remitCountry": "US",
53  "remitState": "FL",
54  "remitZip": "31113",
55  "State": "GA",
56  "StoredMethods": [],
57  "Summary": {
58    "ActiveBills": 2,
59    "PendingBills": 4,
60    "InTransitBills": 3,
61    "PaidBills": 18,
62    "OverdueBills": 1,
63    "ApprovedBills": 5,
64    "DisapprovedBills": 1,
65    "TotalBills": 34,
66    "ActiveBillsAmount": 1250.75,
67    "PendingBillsAmount": 2890.5,
68    "InTransitBillsAmount": 1675.25,
69    "PaidBillsAmount": 15420.8,
70    "OverdueBillsAmount": 425,
71    "ApprovedBillsAmount": 3240.9,
72    "DisapprovedBillsAmount": 180,
73    "TotalBillsAmount": 25083.2
74  },
75  "VendorId": 1,
76  "VendorNumber": "1234",
77  "VendorStatus": 1,
78  "Zip": "31113",
79  "PaymentPortalUrl": "https://greenfield-landscaping.com/pay",
80  "CardAccepted": "yes",
81  "AchAccepted": "unable to determine",
82  "EnrichmentStatus": "fully_enriched",
83  "EnrichedBy": "web_search",
84  "EnrichedAt": "2026-03-05T14:22:10Z",
85  "EnrichmentId": "enrich-3890-a1b2c3d4"
86}

Key fields:

FieldDescription
EnrichmentStatusCurrent enrichment state: not_enriched, partially_enriched, fully_enriched, or fallback_applied.
EnrichedByWhich method resolved the vendor’s payment acceptance info.
PaymentPortalUrlURL for the vendor’s online payment portal, if known.
CardAcceptedWhether the vendor accepts card payments: yes, no, or unable to determine.
AchAcceptedWhether 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:

ConditionMessage
Feature not enabledVendor enrichment isn’t enabled for this organization.
Vendor not found or inactiveVendor not found or isn’t active.
Vendor doesn’t belong to entryVendor doesn’t belong to this entrypoint.
Enrichment already in progressAn enrichment request is already in progress for this vendor.
Missing invoice fileAn 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.

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