Get New Vendor Requests

Syntax
Request Parameters
Sample Response
Response Key/Value Explanations
HTTP Response Codes
Calling the API
- Postman
- cURL
- Python

Syntax

GET /api/new-vendor-requests/

Returns a set of new vendors that satisfy all selected request parameters. The user performing this request has to be authorized to View New Vendor Requests.

Example:

GET /api/new-vendor-requests/?status=1&per_page=20

This sample call will return the first page of New Vendor Requests that are Approved (status=1). Each page of results will have at most 20 results per page in this case.

Request Parameters

Parameter	Type	Description	Example
page	Number	Page number within the paginated result set to return.	page=2 will return the second page
per_page	Number	Number of results to return per page. Default value is 10. The maximum per_page value is 1000.	per_page=20 will return twenty New Vendor Requests per page
status	Number	Filter by registration status: 0 – Pending 1 – Approved 2 – Processed 3 – Connected 4 – Rejected 5 – Returned	status=1 will return only approved New Vendor Requests.
type	Number	Filter by registration type: 0 – Full 1 – Partial 2 – Edit	type=2 will return only Edit Registrations
resubmitted_only	Boolean	When true, return only registrations that have been returned to the payee, and then resubmitted by the payee. Default is false.	resubmitted_only=true will return only registrations that have been returned to the vendor, and then resubmitted by the vendor.
status_change_since	Date	Filter to only return registrations where the status has changed since the specified date. Format: YYYY-MM-DD	status_change_since=2022-12-31 will return all registrations where the status has changed on or after Dec 31st, 2022.
since	Date	Filter to only return registrations submitted by the payee since the specified date. Format: YYYY-MM-DD	since=2022-12-31 will return all registrations that are submitted on or after Dec 31st 2022.
last_n_days	Number	Filter to only return registrations submitted in the last N days	last_n_days=30 will only return the registrations submitted within the last 30 days.
supplier_name	String	Case insensitive filter on the name of the supplier/payee. supplier_name can be a prefix or the exact name of the payee that submitted the registration.	supplier_name=Home%20dep will return registrations submitted by “Home Depot”, and “Home Depot of Wolcott”. Notice the space is represented as %20. Matching is not case sensitive.
tag_name	String	Case insensitive filter on registrations with the specified tag name or a prefix of the tag.	tag_name=test will return all registrations that have tags that look like: Test, Test 1, test 2, etc.
vendor_num	String	Filter by vendor number that this registration is connected to in the ERP.	vendor_num=12345 will return only registrations that are connected with supplier that has vendor number = 12345 in the ERP.
site_code	String	Filter by the site code that this registration is connected to in the ERP.	site_code=2 will return only registrations that are connected with supplier that has site code = 2 in the ERP.
my_pending_only	Boolean	If true, only return pending registrations that can be approved by the requesting user.	my_pending_only=True will only return pending registrations that the requesting user can approve.
id	Number	Filter by the PaymentWorks registration ID.	id=123 will only return registration 123.
tin	String	Filter by tax id (SSN, EIN, ITIN, foreign tax ID) of the payee that submitted the registration.	tin=123456789 will return the registrations submitted by payees with tax ID “123456789”

Sample Response

An example JSON response can be seen here:

{
    "count": 6,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 19657,
            "request_status": "Approved",
            "requesting_company": {
                "id": 12593,
                "name": "Home Depot"
            },
            "ts": "2023-01-11T15:06:45.288495-05:00",
            "user_can_approve": false,
            "user_can_bypass": false,
            "pending_approvers": [],
            "latest_sent_msg_id": null,
            "is_resubmitted": false,
            "last_submitted_ts": "2023-01-11T15:06:45.285381-05:00",
            "request_type": "Partial",
            "registration_routing": {
                "op_code": "new_address",
                "annotation": "",
                "related_site_code": "2",
                "related_vendor_number": "12345"
            },
            "tags": []
        },
        {
            "id": 19654,
            "request_status": "Approved",
            "requesting_company": {
                "id": 12593,
                "name": "Home Depot"
            },
            "ts": "2023-01-11T14:55:00.788375-05:00",
            "user_can_approve": false,
            "user_can_bypass": false,
            "pending_approvers": [],
            "latest_sent_msg_id": null,
            "is_resubmitted": false,
            "last_submitted_ts": "2023-01-11T14:55:00.777605-05:00",
            "request_type": "Partial",
            "registration_routing": {
                "op_code": "new_address",
                "annotation": "",
                "related_site_code": "2",
                "related_vendor_number": "12345"
            },
            "tags": []
        }
    ]

Response Key/Value Explanations

Key	Type	Sample Value	Description
count	Number	17	How many New Vendor Requests were retrieved.
next	URL	`https://paymentworks.com/api/new-vendor-requests/?page=2`	The URL to the next page or null if there are no further pages to return.
previous	URL	`https://paymentworks.com/api/new-vendor-requests/?page=1`	The URL to the previous page or null if this is the first page.
results	Array of JSON objects	[ { New Vendor Request 1 }, { New Vendor Request 2 }, { New Vendor Request 3} … ]	An array of JSON objects where each object is one New Vendor Requests. This array is always at most one page long.

HTTP Response Codes

Status Code	Description
200 OK	Success
400 Bad Request	The 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 Forbidden	Permission Denied – User does not have permission to perform this request
404 Not Found	The resource you requested on the server does not exist
500	The request has failed due to a temporary failure of the server. You can try this request at a later time.
503	The request has failed due to a temporary failure of the server. You can try this request at a later time.

Calling the API

Postman

Call Syntax:

{
	"name": "get_approved_nvrs",
	"request": {
		"auth": {
			"type": "apikey",
			"apikey": [
				{
					"key": "value",
					"value": "Token 500a3XXXXXXXXXXXXXXXXXXXXb1cf",
					"type": "string"
				},
				{
					"key": "key",
					"value": "Authorization",
					"type": "string"
				}
			]
		},
		"method": "GET",
		"header": [],
		"url": {
			"raw": "https://sandbox.paymentworks.com/api/new-vendor-requests/?status=1",
			"protocol": "https",
			"host": [
				"sandbox",
				"paymentworks",
				"com"
			],
			"path": [
				"api",
				"new-vendor-requests",
				""
			],
			"query": [
				{
					"key": "status",
					"value": "1"
				}
			]
		}
	},
	"response": []
}

Sample PostMan call:

cURL

Python

import requests
import json
import os

# These variables should be set as OS environment variables
API_TOKEN = os.environ.get('API_TOKEN')
# The value should be the API url, for example: https://sandbox.paymentworks.com/api/
API_URL = os.environ.get('API_URL')
request_headers={'Accept': 'application/json','Authorization': 'Token ' + API_TOKEN }

# Returns all approved New Vendor Requests
def get_approved_nvrs() :
    resp = None
    request_path = API_URL + 'new-vendor-requests/?status=1'
    try:
        resp = requests.get(url=request_path, 
                            headers=request_headers,
                            timeout=10)
    except Exception as exception:
        print(f'Unexpected {exception=}, {type(exception)=}')
    return resp

# Main function
response = get_approved_nvrs()
if response is not None:
    if response.status_code == 200:
        responses = json.loads(response.text)
        results = responses['results']
        for result in results :
            nvr_id = result['id']
            print(nvr_id)
    else:
        print('Return Status Code ' + response.status_code)