Get Updates

Syntax
Request Parameters
Success Codes
Sample Response
Error Codes
Calling the API
- Postman
- cURL
- Python

Syntax

GET /api/updates/

Returns a set of vendor updates that satisfy all selected request parameters. The user performing this request has to be authorized to View Vendor Company Updates. In addition to this, depending on the nature of the update the following permissions are required: View Vendor Sanction List Reports, View Tax ID Unmasked, View Vendor Payment Details and View Vendor Profiles.

Example:

GET /api/updates/?status=1&per_page=20

This sample call will return all vendor updates that are Approved ( the status is equal to 1 ). It will return twenty results per page. Note, you only want to fetch the approved updates.

Request Parameters

Parameter	Type	Description	Example
page	Number	A page number within the paginated result set.	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 comments per page.
Statius	Number	0 – Pending 1 – Approved 2 – Rejected 3 – Processed 4 – Promoted (handled as a registration)	status=1 will return approved updates only.
status_change_since	Number	Date when the vendor update has last changed its status in yyyy-mm-dd format.	status_change_since=2022-12-31 will return all updates that have changed status on or after Dec 31st 2022.
value_change_since	DateTime	Date when the vendor update has last changed a value in yyyy-mm-dd format.	value_change_since=2022-12-31 will return all updates that have changed values on or after Dec 31st 2022.
since	DateTime	Date when the New Vendor Request was last submitted in yyyy-mm-dd format.	since=2022-12-31 will return all updates that are submitted on or after Dec 31st 2022.
last_n_days	Number	Number of days	last_n_days=30 will return only updates that were added during the last 30 days.
supplier_name	String	The name of the supplier or a prefix of it. The name is not case sensitive.	supplier_name=Home%20dep will return suppliers “Home Depot”, and “Home Depot of Wolcott”. Notice the space is represented as %20. Matching is not case sensitive.
group name	String	bank_address bank_account company corporate_address remittance_address order_address sanction_list_alert custom_form_fields	group_name=corporate_address will return all updates that have changes in the Corporate Address group of fields.
vendor_num	Number	Vendor number that this update is connected to in the ERP.	vendor_num=12345 will return only updates that are connected with supplier that has vendor number = 12345 in the ERP.
site_code	Number	Site code that this update is connected to in the ERP.	site_code=2 will return only update that are connected with supplier that has site code = 2 in the ERP.

Success Codes

HTTP Status Code	Exception	Description
200	Success	It will return a set of vendor updates that satisfy all selected request parameters. The set may be empty if no update satisfies all selected parameters.

Sample Response

Returns a JSON object with one page of results. Example:

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

where:

Key	Type	Sample Value	Description
count	String	17	How many vendor updates were retrieved.
next	String	https://paymentworks.com/api/updates/?page=2	The URL to the next page or null if the number of result is less than per_page (default is 10).
previous	String	https://paymentworks.com/api/updates/?page=1	The URL to the previous page or null if this is the first page.
results	Array of JSON objects	[ { Update 1 }, { Update 2 }, { Update 3} … ]	An array of JSON objects where each object is one Update. This array is always at most one page long.

Each comment is a JSON object. Example:

{
      "id": 22584,
      "ts": "2022-04-12T10:44:25.474805-04:00",
      "status_ts": "2022-04-12T10:48:43.055888-04:00",
      "vendor_nums": [
        {
          "site_codes": [
            "2"
          ],
          "vendor_num": "12345"
        }
      ],
      "vendor_name": "Home depot of Wolcott",
      "group_name": "Company",
      "from_value_display": "Telephone: +12023334444",
      "to_value_display": "Telephone: +12023334445",
      "status": "Approved",
      "field_changes": [
        {
          "field_name": "Telephone",
          "from_value": "+12023334444",
          "to_value": "+12023334445"
        }
      ],
      "user_can_approve": false,
      "pending_approvers": [],
      "user_can_skip": false,
      "user_can_bypass": false,
      "addr_validated": null,
      "bank_validation_status_display": "",
      "bank_verification_reason_context": null,
      "bank_verification_note": null,
      "metadata": {}
}

where some more important key values pairs are:

Key	Type	Sample Value	Description
id	Number	22584	Each update is identified with a numeric id.
vendur_num	String	12345	If vendor that is being updated is connected, this is the id for this vendor in the ERP.
site_code	Array of Strings	[“1”, “2”, “3”]	This is a list of all sites for this vendor that will be affected by this update.
group_name	String	“Company”	What group this update belongs to: bank_address, bank_account, company…
field_name	String	“Telephone”	The field that was changed.
from_value	String	“+12023334444”	The value prior to the change.
to_value	String	“+12023334445”	The new value.

Error Codes

HTTP Status Code	Exception	Description
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	Unauthorized request. The client does not have access rights to the content. Unlike 401, the client’s identity is known to the server.
404	Not Found	The API that you requested does not exist on this server.
500 503	Service Unavailable	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_updates",
	"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/updates/?status=1",
			"protocol": "https",
			"host": [
				"sandbox",
				"paymentworks",
				"com"
			],
			"path": [
				"api",
				"updates",
				""
			],
			"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 updates or an empty list if there are no approved updates
def get_approved_updates():
    resp = None
    request_path = API_URL + 'updates/?status=1'
    try:
       resp = requests.get(url=request_path, 
                           headers=request_headers,
                           timeout=20)
    except Exception as exception:
        print(f'Unexpected {exception=}, {type(exception)=}') 
    return resp

# Main function
response = get_approved_updates()
if response is not None:
    if response.status_code == 200:
        responses = json.loads(response.text)
        updates = responses['results']
        for update in updates:
             print(update)
    else:
        print('Return Status Code ' + str(response.status_code))