Introduction

This document outlines the requirements for the Jobs API. It provides detailed specifications for the API endpoints, authentication methods, request and response parameters, error handling, and rate limiting. These requirements will guide the development and implementation of the API.

Clients will need to complete an API Client Request form to access the API. PCI’s change management process (CRA) will ensure timely and secure onboarding of clients.

Objectives

  • Enable seamless integration with PCI clients.
  • Provide secure and efficient job management and tracking functionalities.
  • Ensure compatibility with existing systems and scalability for future expansions.

API Environments

A dedicated test environment for both the Web UI and REST API’s will be available for authorized users.

Environment URL
Development https://dev-hssearcher.originalimpressions.com/api/v1
Production https://webservices.originalimpressions.com/api/v1

Authentication Management

Create Token

Creates credentials for a client in the system and provides an initial authorization token.

HTTP Method POST
URI Path api/api-users/create
Client Access Yes 
                                        
                                            {
    "company": "SAM",
    "username": "my_username", 
    "password": "73sting123!"
}

Notes

The following fields are REQUIRED in the Request Body (marked in RED above): company, username, password

Response

                                            
                                                {
    "token": "BL4HblahBLahBlahblaHb14hBLAHblahBLahBlahblah",
    "token_type": "bearer",
    "expires_in": "365 days"
}

                                            
                                        
                                            
                                                {
    "message": "Partial Content. The response’s data is filtered based on the request criteria",
}

                                            
                                        
                                            
                                                {
    "message": "Bad Request - The request was invalid or cannot be served. "
}

                                            
                                        
                                            
                                                {
    "message": "Unauthorized - Authentication is required and has failed or has not yet been provided. "
}

Refresh Token

Creates a new token for a client to authenticate when interacting with the API.

HTTP Method POST
URI Path api/api-users/login
Client Access Yes 
                                        
                                            {
    "username": "my_username", 
    "password": "73sting123!"
}

Notes

The following fields are REQUIRED in the Request Body (marked in RED above): company, username, password Usernames can only be created once; subsequent attempts will result in a 422 response.

Response

                                            
                                                {
    "token": "BL4HblahBLahBlahblaHb14hBLAHblahBLahBlahblah",
    "token_type": "bearer",
    "expires_in": "365 days"
}

Schedule Job (Create)

Creates a new Mailing job for scheduling.

HTTP Method POST
URI Path mail/jobs
Client Access Yes 
                                        
                                            {
  "id": "SA1235",
  "accountname": "SAM",
  "customer": "MyClient Corp",
  "customerjobid": "MY100",
  "pickuplocation": "123 Main Street, Boca Raton, FL 33434",
  "shipdate": "2025-04-15",
  "shiptime": "02:30 PM",
  "pcilocation": "FL",
  "targetmaildate": "2025-04-17",
  "quantity": 5000,
  "postagetype": "PCI Permit",
  "estimatedpallets": 3,
  "estimatedgpcs": 1,
  "estimatedtrays": 50,
  "emailrecipients": null,
  "jobnotes": "Special job notes",
  "mailclass": "first class",
  "mailtype": "letters",
  "po": "PO12345",
  "mailowner": "Mail Owner",
  "mailownercrid": 12345678
}

Notes

Please refer to the Field Definitions table for details about each field listed above and below. The following fields are REQUIRED in the Request Body (marked in RED above): id, accountname, customer, customerjobid, pickuplocation, shipdate, shiptime, pcilocation, quantity, postagetype, mailclass Shipdate must be equal to or greater than the current date or a 422 error will occur. Other optional parameters include: clientfile, usps_promotions

Response

                                            
                                                {
    "message": "Success. Job created.",
    "id": "SA1235",
    "syslogid": 99
}

Get Job

Retrieves the details of a job by its ID.

HTTP Method GET
URI Path mail/jobs/{id}
Client Access Yes

Response

                                            
                                                {
    "id": "SA1235",
    "accountname": "SAM",
    "customer": "MyClient Corp",
    "customerjobid": "MY100",
    "pickuplocation": "123 Main Street, Boca Raton, FL 33434",
    "shipdate": "2025-04-15",
    "shiptime": "02:30 PM",
    "pcilocation": "FL",
    "quantity": 5000,
    "estimatedpallets": 3,
    "estimatedgpcs": 1,
    "estimatedtrays": 50,
    "emailrecipients": null,
    "jobnotes": "Sample job notes",
    "postagetype": "PCI Permit",
    "mailclass": "first class",
    "mailtype": "letters",
    "po": "PO12345",
    "mailowner": "Mail Owner",
    "mailownercrid": 1234,
    "targetmaildate": "2025-04-17",
    "createdate": "2025-04-15",
    "createtime": "10:01:51",
    "syslogid": 123,
    "status": "Scheduled",
    "datemailed": null
}

Update Job

Updates permitted fields for a Scheduled job.

HTTP Method PUT
URI Path mail/jobs/{id}
Client Access Yes 
                                        
                                            {
  "accountname": "SAM",
  "customer": "JCC Corp",  
  "customerjobid": "JOB1234",
  "pickuplocation": "123 Main Street, Boca Raton, FL 33434",
  "shipdate": "2025-04-15",
  "shiptime": "02:30 PM",
  "pcilocation": "FL",
  "targetmaildate": "2025-04-17",
  "quantity": 5500,
  "postagetype": "PCI Permit",
  "estimatedpallets": 3,
  "estimatedgpcs": 1,
  "estimatedtrays": 50,
  "emailrecipients": null,
  "jobnotes": "Sample job notes",
  "mailclass": "first class",
  "mailtype": "letters",
  "po": "PO12345",
  "mailowner": "Mail Owner",
  "mailownercrid": 1234
}

Notes

Please refer to the Field Definitions table for details about each field listed above. ‘{id}’ in the URI Path above must be replaced with the JobID to update. Any field used to Schedule a job EXCEPT id can be included in the Request Body and is optional. Also, job details can ONLY be updated while they are still in a ‘Scheduled’ state. The sample response below confirms that scheduled job SA1235 has been updated to a quantity of 5500; as ‘emailrecipients’ is a currently unsupported field, it currently shows up as a field changed to null, even if not included in the Request body.

Response

                                            
                                                {
 "message": "Success. Job updated.",
 "id": "SA1235",
 "updated_fields": {
     "quantity": 5500,
     "emailrecipients": null
 }
}

Delete Job

Deletes a job from the system.

HTTP Method DELETE
URI Path mail/jobs/{id}
Client Access Yes

Response

                                            
                                                {
    "message": "Success. Job deleted",
    "id": "SA1235"
 }

Change Log

May 20th, 2025

Version 1.4

1.4

NewAdded support for Samsara route retrieval APIy

ImprovementOptimized authentication token expiration handling

UpdateModified job scheduling to allow weekend pickups

FixedCorrected rate limit enforcement for client API calls

April 12th, 2025

Version 1.3

1.3

NewImplemented batch job processing improvements

ImprovementEnhanced error messages for invalid job requests

UpdateUpdated targetmaildate validation requirements

FixedResolved JSON response formatting inconsistencies

March 5th, 2025,

Version 1.2

1.2

NewIntroduced email recipient handling for future update

ImprovementStreamlined job status updates for processing phase

UpdateAdjusted postagetype field to support additional value

January 14th, 2025

Version 1.1

1.1

NewCreated initial batch job creation API

UpdateExtended API authentication duration to 365 days

Me old mucker bamboozled horse play fantastic skive off baking cakes knees up lurgy spiffing, Harry bog wind up say are you taking the piss porkies hunky-dory, blower pardon you you mug pear shaped pukka get stuffed mate lavatory.

Related Reading:Child Theming for Layers

Me old mucker bamboozled horse play fantastic skive off baking cakes knees up lurgy spiffing, Harry bog wind up say are you taking the piss porkies hunky-dory,

Related Reading:Child Theming for Layers
Footnote Name A
Lorem ipsum dolor, sit amet consectetur adipisicing elit. Amet voluptas dicta dolor.
Footnote Name B [PDF]
Lorem ipsum dolor, sit amet consectetur adipisicing elit. Amet voluptas dicta dolor.
Footnote Name C
Lorem ipsum dolor, sit amet consectetur adipisicing elit. Amet voluptas dicta dolor.