If you know how to GET data with an API, PUTting or POSTing with an API will be a piece of cake! The requirements are similar, but there are just a couple of differences. Please note that this blog is tailored toward the Lever API. Other APIs may have different requirements.
When GETting data, the download tool typically connects to a text input tool through a URL that specifies where to retrieve the information from. However, this is not the case when uploading or updating data via PUT or POST actions. In these cases, the download tool must connect to the data that the user wants to output and use the website URL to specify where the data should be sent. The new request may require a different authentication key for authorization, which may resemble the process used when GETting data.
The first step is to determine what the goal of the user is. Some example requests that the Lever API allows are tagging information about a candidate onto their profiles and archiving each accordingly based on certain criteria..
The next step is to determine what data, parameters, and/or fields are needed to fulfill these requests, which usually can be found in the documentation. Some API documentations can be more complex than others, so it’s best to read the information thoroughly to know what each call does and test with a dummy, if possible.
As shown in the Lever API documentation, to attach tag information to a candidate’s profile, a root URL ending in “/opportunities/:opportunity/addTags” and the desired tag(s) in the form of an array of strings is required. Optionally, the user performing the call can be specified, but it is not necessary.
To archive a candidate, a root URL ending in “/opportunities/:opportunity/archived” and an archive reason UID are required. The “cleaninterviews” and “requisitionid fields” are optional and may be used if they are desired requests.
These fields need to be formatted as the API documentation indicates. A formula tool may be used to create and format these essential fields. The formula tool below displays the building of new fields required by the tagging functionality of the Lever API.
The first formula creates the URL that will be used to direct where the data will be applied to on the website through the API. The URL format can be found in the documentation, as shown in the image below. For instructions on how to form a request URL, refer to GETting API Authorization with Basic Authentication on Alteryx.
The second formula rewrites the pre-existing field with the correct tag information to later output onto the website. The third formula creates a new field and turns the tag field from the second formula from a string into an array by adding the brackets “[]” at the end of the new field name: “tags”. Please note that field names must match the field names in the documentation exactly, which includes capitalization.
The below formula tool shows how to create the fields needed to archive candidates through the Lever API to archive candidates. The Archive URL indicates which applicants to archive using their specific candidate ID and opportunity ID. A reason ID field indicates the reasoning behind the archive action. The reason field does not need to be formatted as an array of strings. Instead, it can remain as a string. Super Admins can only retrieve the reason IDs on their Lever account.
Once the essential fields have been created, it’s time to apply them to the download tool to output the desired action.
Under the Basic tab of the Download tool, the TAG URL created in the formula tool is inputted into the URL field section.
Under the Headers tab, the first value added is the authorization, which contains the authentication key with the permission to output tags and archive candidates. The permissions must be set on the Lever website by a Super Admin and encoded, similar to the process of GETting API Authorization with Basic Authentication on Alteryx. Additionally, the values “Accept-Encoding: *” and “cache-control: no-cache” have been added to reduce the errors through bad encoding by accepting any encoding types and preventing the saving of the Requests and Responses (R&R) so that it will not be utilized in subsequent responses, respectively (2).
Under the Payloads tab, the HTTP Action has been set to POST, as directed by the Lever API documentation, to upload Tag information onto the candidate profiles. Also, the desired tag information (formatted as an array of strings) is checked off to direct the download tool to upload that specific tag onto the candidate profiles. Alternatively, a static tag could be added manually on the gray box above using the matching name (field name) and value (tag information) created earlier in the formula tool.
Nothing is required to be added or changed onto the Connection tab.
The download tool for archiving candidates will look similar to tagging candidates on Lever.
The only differences are:
- Basic tab: the Archive URL will replace the Tag URL
- Headers tab: the archiving authentication key will replace the tagging authentication key if the permissions are purposefully split up
- Payload tab: the HTTP action is changed to “custom: PUT” and the reason will be checked off instead of the tag[] field.
Now all that is left to do is to click RUN! I hope this helps the next time you need to upload data or make changes to a website through its API.
Sources:
