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 VendorBulkRetrieveVendors endpoint can take more than one vendor ID to retrieve multiple vendors at a time.
To retrieve a single vendor, call RetrieveVendorvendor_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": "annie@acme.com", "phone_number": "1-212-555-4251", "removed": false, "ordinal": 0 } ], "version": 1, "status": "ACTIVE" } }
To retrieve multiple vendors at a time, call BulkRetrieveVendorsvendors_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": "joe@acme.com", "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": "annie@acme.com", "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": "annie@acme.com", "phone_number": "1-212-555-4251", "removed": false, "ordinal": 0 } ], "version": 1, "status": "ACTIVE" } } } }
