Writing to POST endpoints with Merge
Merge's Unified API allows you to add resources by sending JSON payloads to, or 'hitting', post endpoints for supported integrations. This allows you to create new employees, candidates, applications and more. In this guide, we'll walk you through writing data via our API. On a Unified API, you can write data to multiple integrations while following a common schema. This way, you won't have to deal with varying field names and objects across applications.
This example uses Postman as our API client, but you can also use another client of your choice or use a programming language like Python.
Before you get started, you'll want to make sure the integration you are working with has support for POST requests. You can see a comprehensive overview of the supported actions per common model by sending a GET request to the Linked Accounts endpoint (with the relevant linked account token included in the headers as X-Account-Token).
The keyword to look out for here is "CREATE", under the available_model_operations field. In this example, we are checking the available actions for an ATS integration that we want to create candidates on:
The main difference between POST endpoints and GET endpoints is that POST requests typically include JSON payloads in the request body. These contain the data that will be sent to the server to create a resource.
Create a response body under the Body tab of Postman. Select raw and choose JSON as the data type from the dropdown menu to the right. Note that our APIs only accept JSON data, and form data is not accepted. All common model data should be nested inside the model parameter.
Note: Our APIs only accept data in valid JSON form.
Often, you'll need to pass in valid Merge IDs into request bodies for the POST requests to be valid. If you need to retrieve available IDs, use GET requests to look at data in the server.
Be sure to pay close attention to data types; some fields are entered differently based on the category. For example, emails for the POST /employees endpoint (HRIS) are passed through in string fields called personal_email and work_email. The POST /candidates endpoint in the ATS category requires emails to be passed in as an array, as shown:
Another area often required for writes is permissions. Many APIs have restrictions around who can write data, and look out for specific user roles when processing POST requests. This is the case for several of our ATS integrations right now, which require users to have specific permissions for creating candidates and posting them to open jobs.
Permissions are handled by Merge's remote_user_id field, which is passed through as a separate, top-level body parameter. The field indicates the ID of the user submitting the request and allows the server to verify the user's access role. To verify if this parameter is required for a given integration is to use the Linked Accounts endpoint. Look for the required_post_parameters array, as shown in this example for creating candidates on an ATS integration:
An enum, or an enumerated type, is a data type consisting of named values. Enums help to normalize values from different APIs by mapping them to Merge-specific values.
When writing to a POST endpoint with an enum field that you choose to use, you will have to pass in one of the listed values for that field. For example, the POST /Employees endpoint in HRIS includes optional fields for ethnicity, marital_status, gender and employment_status. If you are creating an employee with one or more of these fields, follow the syntax provided to pass in the appropriate values.
Construct the payload with the data you want to write to the server, and click Send:
A response body is returned after a successful request, along with a 201 status code (indicating that a resource has been created):
Many integrations will have required fields for writing to certain endpoints. If these fields are missing from the payload, the POST request will not go through. An error message will notify you if you are missing a required field for that integration.
In this example, the error message informs us that we've missed email_addresses, a required field for posting candidates to this application:
By now, you should be ready to create candidates, employees and more. Have further questions about using our POST endpoints? Contact us at [email protected] to resolve your doubts.