Bulk Barcode Generation

API Documentation

Introduction

The Bulk Barcode products allows users to validate an address and generate either standard or custom barcode. It includes four main APIs: GetToken, File Upload, Get Status, and File Download.

GetToken

The Bulk barcode API is additionally secured requiring the use of Token which can be generated using GetToken API. The token received from the GetToken API must be used to invoke FileUpload, FileStatus and FileDownload APIs.

The token expires in 3600 seconds, therefore a new token must be generated each time the token expires.

The GetToken should not be used in client-side scripting such as Javascript on webpages. It is meant to be used by a system where in no end-user has access to the identity credentials provided by ADDRESSER.

https://api.addresser.com.au/gettoken

Request Body: JSON


{
    "username": "your_username",
    "password": "your_password"
}

Field	Type	Description
username	string	Your Username provided by addresser
password	string	Your Password provided by addresser

Success Response

Use the generated token as the Authorization key in the headers of subsequent API calls.


{
    "statusCode": 200,
    "statusMessage": "Token generated successfully",
    "token": "your_generated_token"
}

API Errors


{
    "errorCode": 4073,
    "errorMessage": "Supplied identifier is invalid."
}

Error Code	Description	Resolution
5000	username is missing.	Parameter 'username' is missing.
5001	username cannot be empty.	Ensure that "username" is not empty for proper functionality.
5002	password is missing.	Parameter 'password' is missing.
5003	password cannot be empty.	Ensure that "password" is not empty for proper functionality.

Response Specification

Field	Type	Description
statusCode	Integer	The HTTP status code indicating a successful response.
statusMessage	String	A descriptive message indicating the success of the token generation process.
token	String	The actual token generated as part of the response.

File Upload

The File Upload API to be used for submitting CSV file for bulk address validation and barcode generation. The CSV file must be provided in a specific format which is explained in the "Request Body: Form-data" sub-section of this document.

NOTE: ADDRESSER prefixes every file with date and time stamp to ensure uniqueness which is returned back in the File Upload API response. Subsequent API operations on the file must use the file name returned by the File Uplaod API.

https://api.addresser.com.au/barcodebulkverifyupload

Request Headers

Field	Type	Description
Authorization	String	Token obtained from the GetToken API
apikey	String	Your API key.
unique_subscriber_id	String	Unique subscriber ID provided by addresser
header	String	"yes" if the file contains headers, "no" otherwise.
column	Integer	Full address column number (starting from 0).
column_index_map	string	Mapping for the CSV file columns (starting from 0) to identify address, customer information, customer infromation encoding and format control code. Example Assuming CSV uploaded has five columns with address (address_col) in column 3, format control code (fcc_col) in column 2, customer information (customerinfo_col) in column 4 and customer infromation encoding (customerinfoencoding_col) in column 5, the below formatted JSON is exptectecd. { "address_col": "2","fcc_col": "1", "customerinfo_col": "3", "customerinfoencoding_col": "4" } address_col Actual address requiring barcode. fcc_col Format control code determining the barcode type. Allowed values - 11 for standard barcode, 59 for custom barcode 2 and 62 for custom barcode 3 customerinfo_col Customer information that needs to be encoded into the barcode. customerinfoencoding_col Character or numeric encoding types. Allowed values "N" (to be used if only integer values 0 -9 used as customer information) or "C" (to be use for values A to Z, space, #, a to z and digits 0 to 9).

Request Body: Form-data

You should export your address list using the CSV file format. The file should meet the following rules:
1) One address per row.
2) There should be a minimum of four columns in the file - address, format control code, customer information and customer information encoding.
3) Other columns can be included, but will be ignored by the system.
4) Maximum rows in the CSV file should not be more than 1000.

Sample python code


import requests

url = "https://api.addresser.com.au/barcodebulkverifyupload"

payload = {}
files=[
  ('file',('yourfilename.csv',open('/D:/yourfilename.csv','rb'),'text/csv'))
]
headers = {
  'apikey': '**************fCLg',
  'Authorization': 'eyJraWQiOiJh*******',
  'unique_subscriber_id': '*******8cec175991',
  'header': 'yes',
  'column': '1'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)

Success Response


{
    "statusCode": 200,
    "statusMessage": "File uploaded successfully",
    "filename": "2024-03-01 02:00:04-yourfilename.csv"
}

Token Error Responses

{
    "message": "Unauthorized"
}

{
    "message": "The incoming token has expired"
}

API Errors


{
    "errorCode": 5015,
    "errorMessage": "Form data file not found"
}

Error Code	Description	Resolution
5000	Uploaded file type is not valid.	Ensure that the uploaded file is in a CSV format only. Check the file type and reupload a valid CSV file.
5002	Subscriber not found	Verify the unique-subscriber-id provided; it should exist in the system. Correct the ID and resubmit.
5003	Internal Server Error	This is a server-side issue.
5004	Uploaded csv file is Empty	Ensure the CSV file contains data. If it's empty, add valid data and upload the file again.
5005	The file uploaded is not utf-8 encoded. Please cross check the file and reupload	Save the file in UTF-8 encoding and reupload it.
200	File uploaded successfully	No action required; the file has been successfully uploaded.
5006	This file is not valid for batch process please check your remaining quota and reupload the file	Verify the file's eligibility for batch processing. Check quota limits and reupload a valid file.
5007	csv File contains special characters in it.	Remove any special characters from the CSV file and reupload.
5008	header value must be yes or no	Set the header value to 'yes' or 'no' as required.
5010	The provided parameters are missing. Please make sure that to provide these parameters	Check and include the required parameters that are missing.
5011	These parameters values must not be empty	Provide non-empty values for the specified parameters.
5012	API key is missing or invalid.	Provide a valid API key or ensure that the key is included in the request.
5014	Please select a file for the bulk validation	Choose a file for bulk validation before submitting the request.
5015	Form data file not found	Ensure that the specified file in the form data exists and is accessible. Check the file path and try again.
5016	Form data key must be 'file'	Use 'file' as the key when submitting form data.
5017	The file is not in correct format. Please check it again and reupload	Verify the file format and structure; reformat or correct the file and try uploading again.
5018	The file contains only header and no addresses to process. Please cross check the header parameter and try again.	Confirm that the header parameter is correctly defined, and the file contains data rows. Adjust the header parameter if needed and reupload.
5019	These json parameters values must not be empty	Provide non-empty values for the specified json parameters.
5020	The provided json parameters are missing. Please make sure that to provide these parameters.	Provide valid json parameters.
5021	The uploaded csv file has incorrect data in the following rows (row no.s). please recheck the columns fcc, custinfo and custinfo encoding and there combinations. For reference please go through the website documentation. (or) Please check the header parameter value as that must match with the file, if the file contain header please keep the header parameter values as 'yes' or else 'no'
5022	The uploaded csv file has empty cells in the following rows (row no.s).
5023	Invalid address column number	Provide valid input parameters for columns as specified in the documentation.
5024	Invalid fcc column number	Provide valid input parameters for columns as specified in the documentation.
5025	Invalid custinfo column number	Provide valid input parameters for columns as specified in the documentation.
5026	Invalid custinfoencoding column number	Provide valid input parameters for columns as specified in the documentation.
5027	The provided json parameter values for 'column_index_map' key are same. Please cross check the JSON parameter values and retry	Provide valid input parameters for columns as specified in the documentation.

Response Specification

Field	Type	Description
statusCode	Integer	The HTTP status code indicating a successful response.
statusMessage	String	A descriptive message indicating the success of the file upload process.
filename	String	The name of the uploaded file, and the original filename is concatenated with the timestamp(prefix).

File Status

The File Status API to be used for retrieving the status of the files uploaded to ADDRESSER for bulk processing. The API provides two ways of retrieving the file status. The first way is to retrieve the status of all files submitted so far, and the second way is to query the status of a specific file.

NOTE: ADDRESSER prefixes every file with date and time stamp to ensure uniqueness which is returned back in the File Upload API response. Subsequent API operations on the file must use the file name returned by the File Uplaod API.

https://api.addresser.com.au/barcodebulkverifystatus

Request Headers

Field	Type	Description
Authorization	String	Token obtained from the GetToken API

Request Body: JSON

(List all files)


{
    "unique-subscriber-id": "your_unique_subscriber_id"
}

(Specific file)


{
    "unique-subscriber-id": "your_unique_subscriber_id",
    "filename": "yourfilename.csv"
}

Success Response


{
    "body": [
        {
            "items": [
                {
                    "batch_started_at": "2024-03-01 02:00:12",
                    "filename": "2024-03-01 02:00:04-yourfilename.csv",
                    "file_downloaded_timestamp": "",
                    "records_failed": 2,
                    "report_filename": "2024-03-01 02:00:04-yourfilename.pdf",
                    "batch_status": "completed",
                    "number_of_records": 17,
                    "quota_used": 0,
                    "records_succeeded": 15,
                    "failed_reason": "None",
                    "uploaded_timestamp": "2024-03-01 02:00:04"
                }
            ],
            "unique-subscriber-id": "****-****-****-019d1****"
        }
    ],
    "statusCode": 200,
    "response": "success"
}

Token Error Responses

{
    "message": "Unauthorized"
}

{
    "message": "The incoming token has expired"
}

API Errors


{
    "errorCode": 4010,
    "errorMessage": "Invalid input fields provided."
}

Error Code	Description	Resolution
4010	Invalid input fields provided.	Provide valid Input fields for proper functionality.
4018	Internal Server Error	This is a server-side issue.
4020	Invalid unique-subscriber-id.	Verify the unique-subscriber-id provided; it should exist in the system. Correct the ID and resubmit.

Response Specification

Field	Type	Description
body	Array	Contains an array with a single object representing the main response body.
items	Array	Contains an array with a single or multiple objects representing details about the processed batch.
batch_started_at	String	Timestamp indicating when the batch processing started
filename	String	The name of the processed file with the timestamp.
file_downloaded_timestamp	String	Timestamp indicating when the file was downloaded (empty if not downloaded).
records_failed	String	The number of records that failed during processing.
report_filename	String	The name of the generated report file with the timestamp.
batch_status	String	The status of the batch processing (e.g., "completed").
number_of_records	String	Total number of records in the batch.
quota_used	String	The quota used for processing the batch.
records_succeeded	String	The number of records that succeeded during processing.
failed_reason	String	Reason for failure (e.g., "None" if no failures).
uploaded_timestamp	String	Timestamp indicating when the file was uploaded.

File Download

The File Download API to be used for downloading processed file submitted to ADDRESSER for bulk address validation. Please note only files with the status "Completed" are available for download.

NOTE: ADDRESSER prefixes every file with date and time stamp to ensure uniqueness which is returned back in the File Upload API response. Subsequent API operations on the file must use the file name returned by the File Uplaod API.

https://api.addresser.com.au/barcodebulkverifyfiledownload?unique_sub=70bxxxxxx-xxxxxx-6be95d&file=2024-05-28 08:45:39-Demo_barcode_bulk_upload.csv

Request Headers

Field	Type	Description
Authorization	String	Token obtained from the GetToken API
apikey	String	Your API key.

Request Parameters

Field	Type	Description
unique_sub	string	Unique subscriber ID provided by Addresser
file	string	Filename you want to download.

Success Response

The file will be downloaded in its original CSV format.

Token Error Responses

{
    "message": "Unauthorized"
}

{
    "message": "The incoming token has expired"
}

API Errors


{
    "errorCode": 103,
    "errorMessage": "File not found"
}

Error Code	Description	Resolution
101	The unique subscriber id not found.	Verify the specified unique subscriber ID; ensure it exists in the system. If correct, check the file association with the ID.
5010	Internal Server Error	This is a server-side issue.
103	File not found	The specified file is not found. Double-check the file name.
104	The key parameter must be 'file'	The specified key parameter must be 'file'. Double-check the parameter provided.
105	The key parameter must be 'unique_sub'	The specified key parameter must be 'unique_sub'. Double-check the parameter provided.
106	The key parameter 'file' and 'unique_sub' is missing	The key parameters 'file' and 'unique_sub' is missing. Double-check the parameter provided.
107	The key parameter 'file' is empty	The key parameter 'file' is empty. Double-check the parameter provided.
108	The key parameter 'unique_sub' is empty	The key parameter 'unique_sub' is empty. Double-check the parameter provided.

Response Specification

The file will be retrieved in its original CSV format,featuring additional columns appended to include response data.