Applies to: Vendors API
Learn how to retrieve vendors of specified IDs or search for vendors based on specified query conditions.
If you know the ID of a Vendor object, you can call the RetrieveVendor or BulkRetrieveVendors endpoint to retrieve the vendor object. The BulkRetrieveVendors endpoint can take more than one vendor ID to retrieve multiple vendors at a time.
To retrieve a single vendor, call RetrieveVendor while specifying the vendor's ID value as the vendor_id path parameter value.
The following example shows how to call RetrieveVendor to retrieve a vendor of a known vendor ID:
Retrieve vendor
The successful response returns a payload similar to the following:
{
"vendor": {
"id": "CARJMAFUWDYBTPO2",
"created_at": "2022-01-16T03:57:11.128Z",
"updated_at": "2022-01-16T03:57:11.128Z",
"name": "Vendor 2A",
"contacts": [
{
"id": "IPSTXCGSCXC5HU2P",
"name": "Vendor B's Contact",
"email_address": "[email protected]",
"phone_number": "1-212-555-4251",
"removed": false,
"ordinal": 0
}
],
"version": 1,
"status": "ACTIVE"
}
}To retrieve multiple vendors at a time, call BulkRetrieveVendors while specify the IDs of the vendors in the vendors_ids list of the request payload.
The following example retrieves two vendors with the CARJMAFUWDYBTPO2 and 5VPCRLENAFZXFZNA IDs:
Bulk retrieve vendors
When successful, the response returns a payload similar to the following, where the responses object is a map of vendors indexed by the vendor ID:
{
"responses": {
"5VPCRLENAFZXFZNA": {
"vendor": {
"id": "5VPCRLENAFZXFZNA",
"created_at": "2022-01-16T03:57:11.205Z",
"updated_at": "2022-01-16T03:57:11.205Z",
"name": "Vendor A",
"address": {
"address_line_1": "101 Main Street",
"address_line_2": "Suite 1",
"locality": "City",
"administrative_district_level_1": "State",
"postal_code": "10003",
"country": "US"
},
"contacts": [
{
"id": "HB5S4SB2EXYGKVJ3",
"name": "Vendor A's Contact",
"email_address": "[email protected]",
"phone_number": "1-212-555-4250",
"removed": false,
"ordinal": 0
}
],
"account_number": "4025391",
"note": "a vendor",
"version": 1,
"status": "ACTIVE"
}
},
"CARJMAFUWDYBTPO2": {
"vendor": {
"id": "CARJMAFUWDYBTPO2",
"created_at": "2022-01-16T03:57:11.128Z",
"updated_at": "2022-01-16T03:57:11.128Z",
"name": "Vendor 2A",
"contacts": [
{
"id": "IPSTXCGSCXC5HU2P",
"name": "Vendor B's Contact",
"email_address": "[email protected]",
"phone_number": "1-212-555-4251",
"removed": false,
"ordinal": 0
}
],
"version": 1,
"status": "ACTIVE"
}
}
}
}If you specify an invalid or non-existing vendor ID in the input parameter of vendor_ids in the BulkRetrieveVendors request call, as illustrated:
{
"vendor_ids": ["CARJMAFUWDYBTPO2", "5VPCRLENAFZXFZNA_"]
}The response returns a payload similar to the following, where the found vendor (CARJMAFUWDYBTPO2) is returned as expected, but for the invalid or non-existing vendor ID (5VPCRLENAFZXFZNA_) an error is returned:
{
"responses": {
"5VPCRLENAFZXFZNA_": {
"errors": [
{
"category": "INVALID_REQUEST_ERROR",
"code": "NOT_FOUND",
"detail": "Resource not found."
}
]
},
"CARJMAFUWDYBTPO2": {
"vendor": {
"id": "CARJMAFUWDYBTPO2",
"created_at": "2022-01-16T03:57:11.128Z",
"updated_at": "2022-01-16T03:57:11.128Z",
"name": "Vendor 2A",
"contacts": [
{
"id": "IPSTXCGSCXC5HU2P",
"name": "Vendor B's Contact",
"email_address": "[email protected]",
"phone_number": "1-212-555-4251",
"removed": false,
"ordinal": 0
}
],
"version": 1,
"status": "ACTIVE"
}
}
}
}