Get Suppliers

Syntax

GET /api/suppliers/

Returns a set of suppliers that satisfy all selected request parameters. The user performing this request has to be authorized to View Suppliers.

Example:

GET /api/suppliers/?supplier_name=Best&per_page=20

This sample call will return all suppliers that have “Best” in their name. It will return twenty results per page.

Request Parameters

ParameterTypeDescriptionExample
pageNumberA page number within the paginated result set.page=2 will return the second page.
per_pageNumberNumber of results to return per page. Default value is 10. The maxiumum per_page value is 1000.per_page=20 will return twenty suppliers per page.
supplier_nameStringThe name of the supplier or a substring contained in the name. The name is case insensitive.supplier_name=Home%20dep will return suppliers “Home Depot”, and “Best Home Depot”. Notice the space is represented as %20.
vendor_numStringThe ID of the supplier in the ERP.vendor_num=234 will return suppliers with ERP ID 12345, 1234 and 2345.
site_codeStringThe site ID of the supplier in the ERP. This parameter should be used together with vendor_num parameter.site_code=2 will return suppliers with ERP site codes of 12, 23 and 123
address1StringThe first line of the address of the supplier or a substring contained in the first line. Matching is case insensitive.address1=hess%20d will return suppliers on address “Hess drive”, and “25 Hess drive of Wolcott”. Notice the space is represented as %20.
address2StringThe second line of the address of the supplier or a substring contained in the first line. Matching is case insensitive.address2=hess%20d will return suppliers on address “Hess drive”, and “25 Hess drive of Wolcott”. Notice the space is represented as %20.
cityStringThe city of the supplier or a substring contained in the city. Matching is case insensitive.city=ew%20y will return suppliers where city is “New York”, and “Few Yolks”. Notice the space is represented as %20.
stateStringThe state of the supplier. Matching is case insensitive.state=CT will return suppliers from Connecticut.
zipcodeStringThe zip code of the supplier.zipcode=06716 will return suppliers from zip code 06716.
countryStringThe 2-letter country code for the supplier.country=US will return suppliers from United States.
address_typeNumber

  • 0 = No Address Type Specified
  • 1 = Corporate Address
  • 2 = Remittance Address
  • 3 = Order Address

address_type=2 will return only suppliers that have a Remittance Address.
contact_emailEmailThe contact email associated with this supplier.contact_email=some@host.net will return the supplier with contact email some@host.net
connectedBooleanFlag indicating whether or not the uploaded supplier is connected to a payeewith a PaymentWorks account.connected=true will return uploaded suppliers that are already connected to a payee with a PaymentWorks account.
tinStringTax ID of the suppliertin=123456789 will return supplier with that TIN number.

Sample Response

Returns a JSON object that contains the status of the upload and how many suppliers were actually uploaded. Example:

{
  "count": 17,
  "next": https://paymentworks.com/api/suppliers/?page=2,
  "previous": null,
  "results": [ ... 
  ]
}

Response Key/Value Explanations

KeyTypeDescriptionSample Value
countNumberNumber of suppliers retrieved.17
nextURLThe URL to the next page or null if there are no further pages.https://paymentworks.com/api/suppliers/?page=2
previousURLThe URL to the previous page or null if this is the first page.https://paymentworks.com/api/suppliers/?page=1
resultsArray of JSON objects[ { Supplier 1 },

{ Supplier 2 },

{ Supplier 3} … ]

An array of JSON objects where each object is one Supplier. This array is always at most one page long.

Each Supplier is a JSON object with some more important fields for this supplier. Example:

 {
      "id": 7197244,
      "connection_status": {
        "is_connected": false
      },
      "vendor_num": "0000005466",
      "site_code": "1",
      "supplier_name": "McGraw-Hill Companies",
      "address_type": 0,
      "address_pay_to": null,
      "address1": "PO Box 546",
      "address2": null,
      "city": "Blacklick",
      "state": "OH",
      "country": "US",
      "zipcode": "43004",
      "tin": "776655443",
      "ts": "2022-05-25T13:11:13.532995-04:00",
      "last_modified": "2022-05-25T13:11:31.140773-04:00",
      "normalized_vendor_num": "5466",
      "contact_email": null,
      "request_id": null,
      "status": null,
      "additional_field_1": null,
      "additional_field_2": null,
      "additional_field_3": null,
      "additional_field_4": null,
      "additional_field_5": null,
      "bank_acct_num": null,
      "bank_name": null,
      "routing_num": null,
      "name_on_acct": null,
      "bank_country": null,
      "payment_method": null,
      "hashed_bank_acct_num": null,
      "virtual_card_category": null,
      "acct": 14268,
      "acct_company": 12589
    },

where some of the more important key/value pairs include:

KeyTypeDescriptionSample Value
idNumerEach supplier is identified by a numeric ID.7197244
vendor_numStringThis is the vendor ID for this supplier in the ERP.12345
site_codeStringThe site ID for this vendor in the ERP. 23
address_typeString

  • 0 – Not Specified
  • 1 – Corporate Address
  • 2 – Remittance Address
  • 3 – Order Address

The type of address

HTTP Response Codes

Status CodeDescription
200 OKSuccess
400 Bad RequestThe request could not be understood by the server due to incorrect syntax.
401 Unauthenticated
The request requires user authentication information. Your API token is missing or invalid.
403 ForbiddenPermission Denied – User does not have permission to perform this request
404 Not FoundThe resource you requested on the server does not exist
500The request has failed due to a temporary failure of the server. You can try this request at a later time.
503The request has failed due to a temporary failure of the server. You can try this request at a later time.

Calling the API

Call Syntax:

{
	"name": "get_suppliers",
	"request": {
		"auth": {
			"type": "apikey",
			"apikey": {
				"value": "Token 500aXXXXXXXXXXXXXXXXXXXXXXXX6b1cf",
				"key": "Authorization"
			}
		},
		"method": "GET",
		"header": [],
		"url": "https://sandbox.paymentworks.com/api/suppliers"
	},
	"response": []
}

Sample PostMan call: