Enrich vendors with the API
This guide covers how to integrate vendor enrichment into your application using the Payabli API. For background on how enrichment works, see Vendor enrichment.
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.
To add the AI outreach call as a third stage, set scheduleCallIfNeeded to true. When the invoice scan and web search return insufficient payment acceptance info, Payabli schedules a call to the vendor. See Schedule an outreach call for behavior and requirements. This option is in beta.
Response
The response includes the enrichment status and, when applyEnrichmentData is false, the raw extraction results.
When applyEnrichmentData is true, the extracted data is written to the vendor record and also returned in the response.
Response status values
Handling the response
After receiving enrichment results in review mode (applyEnrichmentData: false):
- Display the extracted data from
enrichmentDatato the user for confirmation. - 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. The vendorNumber field is required.
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.
When the scan succeeds, the system:
- Extracts vendor contact information and creates or matches a vendor using the extracted name and address.
- Populates bill fields like invoice number, amount due, and due date from the scan results (empty-field-only).
- Attaches the vendor to the bill.
The same empty-field-only rule applies — your request values always take precedence.
Schedule an outreach call
Use the schedule outreach call endpoint to have an AI agent call a vendor and collect their preferred payment method and contact email. This is the third enrichment stage. Use it when invoice scanning and web search can’t determine how a vendor wants to be paid.
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.
Request
At minimum, provide the vendorId. Pass a phone number (digits only) to override the vendor’s stored phone, or omit it to call the number on the vendor’s record. The call is scheduled for the next business day at around 9 AM in the vendor’s timezone unless you set sendNow to true.
Key request fields:
Response
A successful request returns the call schedule identifier, the associated enrichment ID, the scheduled call date, and the schedule status.
Error handling
The schedule outreach call endpoint returns HTTP 400 or 429 with a descriptive message:
Read enrichment status
The get vendor endpoint returns enrichment fields directly on the vendor response:
Key fields:
Read outreach call status
The get outreach call status endpoint returns the latest outreach call activity for a vendor. The response is a composite object: the state field tells you which block is populated. This endpoint is in beta.
The state field is one of four values:
When state is successful, the completed block includes a transcript field with the full call transcript. It’s null when no transcript is available.
Error handling
The enrich endpoint returns specific error messages when enrichment can’t proceed:
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.
Prerequisites
- Manage vendors with the API - You need to understand vendor records before enriching them