Announcing Our New Jobs API

As part of our ongoing commitment to provide the best developer experience, we're excited to announce the release of our new Jobs API, which will simplify the developer experience for managing Smart Notifications.

Through research and feedback from our developer community, we saw an opportunity to provide a more streamlined and straightforward experience for creating Smart Notifications.


There were a number of specific goals we wanted to achieve in developing the new Jobs API, specifically to improve the following:

  • Developer Experience

  • Performance

  • Resilience

  • Validation

We'll dive into each below.

Improved Developer Experience

The new Job API provides a simpler and improved developer experience, enabling developers to implement something akin to a ‘fire and forget' model to manage Smart Notifications within Workgrid. The new Jobs API eliminates the need for developers to understand unnecessary details as it relates to the internal workings of a Smart Notification and instead simply allows developers to focus on the context of a Smart Notification request. More information on this specifically can be found below.

Improved Performance

Previously, Smart Notifications APIs were synchronous which restricted the ability to deliver a single Smart Notification to larger audiences and forced developers to split the creation of a Smart Notification across multiple requests.

Our new Jobs API on the other hand is entirely asynchronous, enabling Workgrid to deliver Smart Notifications to significantly larger audiences. It works by taking your request to create a Smart Notification, returning a link to a Job ID, and begins immediately processing your request in the background. Furthermore, our APIs support checking the status of the job if you need it for your use case.

Improved Resilience

Our move to asynchronous processing affords us the ability to improve the resiliency within our architecture. The new Jobs API implements several architectural approaches to ensure your Smart Notification request is delivered to the intended users once its verified that Workgrid has “accepted” your Smart Notification request.

Improved Validation

Workgrid Smart Notifications provide powerful functionality for developers to create engaging content for end users. The new Jobs API includes an improved validation process, ensuring confidence that the Smart Notifications curated will appear correctly to end users.

New Public API Documentation

New public API documentation is also now available with the release of the Jobs API and it's accessible here: Workgrid API.

What is it?

The Jobs API is the new API you use to manage Smart Notifications in Workgrid. The Jobs API is not solely specific to Smart Notifications but it was developed with Smart Notifications as its initial use case. Jobs in Workgrid have a lifecycle as shown below:

%0 created CREATED processing PROCESSING created->processing completed COMPLETED processing->completed error   ERROR   processing->error

In the context of Smart Notifications you create a job to either create or delete Smart Notifications. Every job that is created in Workgrid has a jobId that you can use to invoke the GET Job method in our API to retrieve the current status.

As mentioned above this new asynchronous jobs model allows you to treat Workgrid as a side-effect in a 'fire and forget' model. One of the key features that enables a 'fire and forget' model is a correlation identifier. You can provide a correlationId with every job request that represents something meaningful from your source system. Most often this is the transaction identifier from your source system. Multiple job requests to Workgrid for the same correlationId will be processed in the order they are sent. Using correlationId means you no longer have to maintain any Workgrid state because Workgrid will maintain that state on your behalf.

For more details on Smart Notifications and examples on how you can use the new Jobs API for approvals use cases see the documentation below:

Deprecating the Existing APIs

The existing Smart Notifications APIs are now deprecated and you will need to migrate to our new Jobs API by September, 30th, 2019.

We Want Your Feedback

We're committed to supporting our developers and providing the utmost level of support and resources for building on the Workgrid platform. If you have any questions, concerns, or feedback about our new Jobs API please reach out to your Workgrid Customer Success Representative.