Manage vendors with the API

Vendors are the entities that provide goods or services to paypoints and organizations. They’re who gets paid in money out (pay out) transactions. Before you can use vendors in bills and payouts, you must add them. This guide explains how to add and manage vendors using the Payabli API.

Create a vendor

To create a vendor record, send a POST request to the /api/Vendor/single/{entry} endpoint.

For complete details, see the API reference for this endpoint.

This example creates a new vendor record in the entrypoint 8cfec329267.

1
curl -X POST https://api-sandbox.payabli.com/api/Vendor/single/8cfec329267 \
2
     -H "requestToken: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "vendorNumber": "1234",
6
  "address1": "123 Ocean Drive",
7
  "address2": "Suite 400",
8
  "billingData": {
9
    "accountNumber": "123123123",
10
    "bankAccountFunction": 0,
11
    "bankAccountHolderName": "Gruzya Adventure Outfitters LLC",
12
    "bankAccountHolderType": "Business",
13
    "bankName": "Country Bank",
14
    "id": 123,
15
    "routingAccount": "123123123",
16
    "typeAccount": "Checking"
17
  },
18
  "city": "Miami",
19
  "contacts": [
20
    {
21
      "contactEmail": "example@email.com",
22
      "contactName": "Herman Martinez",
23
      "contactPhone": "3055550000",
24
      "contactTitle": "Owner"
25
    }
26
  ],
27
  "country": "US",
28
  "customerVendorAccount": "A-37622",
29
  "ein": "12-3456789",
30
  "email": "example@email.com",
31
  "internalReferenceId": 123,
32
  "locationCode": "MIA123",
33
  "mcc": "7777",
34
  "name1": "Herman\'s Coatings and Masonry",
35
  "name2": "<string>",
36
  "payeeName1": "<string>",
37
  "payeeName2": "<string>",
38
  "paymentMethod": "managed",
39
  "phone": "5555555555",
40
  "remitAddress1": "123 Walnut Street",
41
  "remitAddress2": "Suite 900",
42
  "remitCity": "Miami",
43
  "remitCountry": "US",
44
  "remitState": "FL",
45
  "remitZip": "31113",
46
  "state": "FL",
47
  "vendorStatus": 1,
48
  "zip": "33139"
49
}'

A successful request returns a JSON response. The IdVendor is returned as responseData.

1
{
2
  "responseText": "Success",
3
  "isSuccess": true,
4
  "responseCode": 1,
5
  "responseData": 3890
6
}

Field requirements and validation

When you create or update a vendor, Payabli validates each field according to the following rules.

General information fields

These fields identify the vendor and apply to every create or update request.

Address fields

Address fields follow an all-or-nothing rule: if you provide any address field, then all required address fields must be present and valid. You can’t submit a partial address. This applies to the primary address and remittance address independently. You can provide one without the other, but each group must be complete.

Primary address

These fields make up the vendor’s main business address.

Remittance address

The remittance address is where payment should be sent when it’s different from the primary address. The same validation rules apply.

State and country validation

The state value is validated against the country value:

Common validation errors

Import vendors

You can import a list of vendors into Payabli using the API. This is useful if you have many vendors to add at once, or if you want to automate the process. Before you get started, download the example CSV file and open it with the editor of your choice. Use it as an example to help you build your import file.

To import a list of vendors, send a POST request to the /api/Import/vendorsForm/{entrypoint} endpoint, with an attached CSV file.

This example imports vendorImport.csv for the entrypoint e56ce00572.

1
curl -X POST https://api-sandbox.payabli.com/api/Import/vendorsForm/8cfec329267 \
2
     -H "requestToken: <apiKey>" \
3
     -H "Content-Type: multipart/form-data" \
4
     -F file=@<file1>

A successful request returns a JSON response with the number of added and rejected records, and any errors. The imported data is now available for use, and you can confirm by checking PartnerHub or PayHub.

1
{
2
  "responseText": "Success",
3
  "isSuccess": true,
4
  "pageIdentifier": "null",
5
  "responseCode": 1,
6
  "responseData": {
7
    "added": 26,
8
    "errors": [
9
      "errors",
10
      "errors"
11
    ],
12
    "rejected": 2
13
  }
14
}

After you import vendors, you can manage them with the API. For example, you can update vendor information, manage payment methods, and create bills associated with specific vendors.

Manage vendors

You can use the API to manage existing vendors, including updating their information, deleting them, and retrieving their details. See these endpoint references for more information:

• Update Vendor
• Delete Vendor
• Get Vendor

Vendor status

In vendor endpoints and endpoints that return vendor data, the vendor status field is VendorStatus.

Enrich vendors

You can use AI-powered vendor enrichment to automatically gather payment acceptance info and contact information for your vendors. Enrichment scans invoices and searches the web to fill in vendor details, reducing manual research. See Vendor enrichment for an overview, or Enrich vendors with the API for implementation details.

Related resources

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