Submitting Requests via API
NOTE: API Access is not included in every Workzone license. For details on upgrading your team's Workzone license, please contact us at help@workzone.com.
Workzone's API Access provides a means for requests to be submitted through third party platforms and other systems. This article will provide some initial guidance on how to leverage API Access in Workzone to be able to submit requests outside of Workzone altogether, though each custom request form established in Workzone can have it's own unique characteristics to take into account (such as Conditional Logic). This article will also assume that your Workzone site has at least one, previously established, custom request form created.
IN THIS ARTICLE
NOTE: In many of the examples described in this article, there are references to the term [COMPANYNAME]. When [COMPANYNAME] is used, it is in direct reference to the first portion of the Workzone site URL of your team/organization. For example, if your Workzone site login is found at "myteam.sharedwork.com" your [COMPANYNAME] would be "myteam".
Interactive API Documentation
Your Workzone site's interactive REST API documentation can be found at the address [COMPANYNAME].sharedwork.com/apidoc. Use this API documentation to gather specific information for submitting a request, as the data in this documentation is specific to your team's Workzone site.
NOTE: If Workzone's API settings does not have app already created, as described here, you will not be able to fully utilize the Interactive API Documentation page. Create an app to avoid authentication errors on that page.
To begin, you'll need to identify the formID for the Workzone request form you will be using to submit requests from the external system. The API "GET" request for Workzone that returns a list of request forms is detailed here:
[COMPANYNAME].sharedwork.com/apidoc/#!/REQUESTS/getRequestForms
In addition to the formID, you will also need to determine the workspaceID for the workspace where the API-submitted project requests will initially reside in Workzone. Workzone provides a list of workspaces using the API "GET" request detailed here:
[COMPANYNAME].sharedwork.com/apidoc/#!/WORKSPACES/getWorkspaces
Also, unless submitting public facing requests, you will need to determine the userID (also known as requesterID) for the user(s) submitting project requests into Workzone. (Public requests always use a requesterID of 0 and require a requesterName and requesterEmail for submission via Workzone's API.) A list of users is provided with the API "GET" request detailed here:
[COMPANYNAME].sharedwork.com/apidoc/#!/USERS/getUsers
Once you have determined the specific formID, you will need to identify the sections, questions, and options for the specified form. This is done with the API "GET" request for Workzone detailed here:
[COMPANYNAME].sharedwork.com/apidoc/#!/REQUESTS/getRequestForm
After gathering all of the data described above, you can use it to submit new project requests with Workzone's API "POST" request, detailed here:
[COMPANYNAME].sharedwork.com/apidoc/#!/REQUESTS/submitRequest
Posting a Project Request
With the information identified in the above section, the next step is to use an API "POST" request.
Use of the API "POST" request requires authorization with a Bearer Token. You can determine the Bearer Token in the Curl text of Workzone's API documentation ([COMPANYNAME].sharedwork.com/apidoc/#!/REQUESTS/submitRequest has this information), in the example seen here:
With the authorization included in the API "POST" request, the remaining data must be an exact match to the specific request form that has been configured within Workzone.
In total, the following values should be included:
| formID | This value is determined from the API request found at: [API DOC ADDRESS] + #!/REQUESTS/getRequestForms |
| workspaceID | This value is determined from the API request found at: [API DOC ADDRESS] + #!/WORKSPACES/getWorkspaces |
| projectTitle | This is uniquely determined determined text that will label the particular request, such as "My Request" |
| requesterID* | This value is either a "0" for public requests or determined from the API request detailed here: [API DOC ADDRESS] + #!/USERS/getUsers |
| requesterName* | For public requests, the name of the individual submitting the request is entered here, "John Doe" for example |
| requesterEmail* | The email address of the public requester |
| requestedDeadline | The deadline date of the request, which can be restricted to not fall within a set number of working days (specified by the form) |
| question_[NUMBER}** | The customized answer(s) to the question(s) on the form, identified in the Response Body of: [API DOC ADDRESS] + #!/REQUESTS/submitRequest |
NOTE: [API DOC ADDRESS] in the table above refers to [COMPANYNAME].sharedwork.com/apidoc/
*If the request is NOT a public request, these values should not be included in the API "POST" request
**A typical form will have several questions, each with their own unique [NUMBER], and the questions will also need to follow the Conditional Logic applied to the form.
When submitting values for checkboxes, the parameter name must be listed in the query string for each value. If both boxes are checked in an example such as this:
...the submission would be "question123=Grayscale&question123=Color". Multiple checked boxes should NOT be comma-separated or otherwise grouped together in a single question entry (e.g., "question123=Grayscale,Color"). This is incorrect and won't work.
Example of Submitting a Request
Here is an example of what would be filled out in a submitted request with a custom form setup inside of Workzone:
This is what the data would look like that is included in the API "POST" request that would match filling out the form as seen above:
| formID | 12345 |
| workspaceID | 987654 |
| projectTitle | My Pet's Profile |
| requesterID | 40302010 |
| requestedDeadline | 2022-07-15 |
| question_7654321 | Cat |
| question_7654322 | Tabby |
| question_7654323 | Playing with string |
With all of the above data and the proper Bearer Token set, the URL for the API "POST" request would read as: