Inbound requests are custom inbound endpoints that you can create for your clients or vendors to transform the information brought in from the client/vendor into a standard payload for our public API, and then call upon that API to take the necessary action(s). 

This guide explains how to create and edit an Inbound request.

Create / Edit Inbound requests

Open the Inbound Requests list and click the + Create New Request button. When clicked, a new page will open where you can enter the following details:

Basic Information section

• Request Name – The name of the request.
• Request Description – The request description, if you'd like to include one.
• Request method – The type of request. Options include:
  • GET
  • POST
  • PUT
  • PATCH
  • DELETE
• Request endpoint – The endpoint you are wanting to send this information. Everything except the end of the endpoint will be autofilled based on the instance (Staging, Production, etc.) and client account. The end can be any URL-valid string and is what should be given to anyone trying to access this custom endpoint.
• Only Consume Payload with Declared Mapping – This only displays for Inbound Requests and will be enabled by default. This ensures that only declared mapping will be consumed from the payload.
• Endpoint Action – The action that should occur upon receiving a request to this endpoint. Options includ:
  • Create candidate
  • Update candidate
  • Schedule interview
  • Replace Candidate Attributes
  • Patch Candidate Attributes
  • Delete candidate

Request Mapping section

Request Mapping is used for translating the information passed to the custom endpoint into System Attributes. The request being passed will automatically be normalized to JSON. There are three parts to a Request Map:

• System Attribute – The attribute that should be populated with the request value. Default attributes will be selected based on the Endpoint Action selected.
• Request Value – The location of the desired value in the JSON request.
• Modifications – A Mapped Values set which will use the Request Value as input and saves the output into the given system attribute. If no modification is required there is an option for None.

Headers section

The Key and Value pairs added here are sent at the top of the payload and labeled as headers. Upon sending, some headers may be added to the request automatically based on other information in the request. 

You can add additional headers by clicking the + Add Header button and entering in the Key and Value fields that display.

Success Response Payload section

This section is the response to send back to the requester upon success. The body can be formatted as JSON or XML and contains the core information sent in the request. JSON uses Key and Value pairs and objects, XML does not. Google has more information on XML.

• Note: The Token Library is also available here.

Response Code Map section

This section is used to overwrite the response code given. This is useful in multiple situations:

• An API always sends back the same response code because it isn’t built well.
• An API sends back the same response code for very similar situations, but we want to note the differences in audit logs.

This section includes the following:

• Response Value – The location of the value to be interpreted in the response JSON. This value could represent a response code and directly be used to overwrite the response code (Modification = None). More commonly, this is an arbitrary value which is used in tandem with a response map (Modification).
• Modifications – A Response Map in which the inputs are values that may be found in the Response Value and the outputs are corresponding desired response codes.
• Error Alerts
  • Employees – A select set of users who will be notified via email if a request gets an error response code.
  • Alert Subject – The subject line of the alert email.
    • Note: These emails will include the following details:
      • Status – The response status.
      • Request Name – The name of the request in Paradox that failed.
      • Request Type – The type of integration request.
      • Account Name – Name of the Paradox Account.
      • Candidate ID – The ID of the candidate that failed.
      • Candidate Full Name – The candidate’s full name.
      • View Response – Clicking this button will take the user into the Audit Logs directly into the failed request.