Testing Merge's Unified API via Postman
Postman API is an API client to help developers test, share and document APIs. This is a useful tool to test sending requests to Merge's API endpoints whenever you're setting up an integration. In this guide, we'll configure and use Postman to send successful requests to the appropriate Merge API endpoints.
When sending requests to Merge endpoints, you will need to pass 2 authentication keys to the Merge API to identify yourself as an authorized user. Follow this guide on where to find them:
There are a few ways to get started:
- (Recommended) Use Merge's Public Postman Workspace
- Import Merge's APIs into Postman using OpenAPI schemas
- Manual setup
You'll be able to fork our collections and/or put in your access tokens as environment variables and get going quickly.
Postman also includes support for importing OpenAPI Specifications, which are API description formats for REST APIs. Merge provides OpenAPI 3.0 schemas for all 4 of the currently supported categories: HRIS, ATS, Accounting, and Ticketing.
This is a convenient way to quickly set up your testing configurations with all the relevant common models included. You just have to configure your authentication details and you'll be good to go.
Click the "Import" button, and go to the Link tab, where you can paste the link for the category you're testing. For this example, we're importing the schema for the ATS category:
Endpoints will be imported as folders, and include example responses:
Create a new request in Postman and we'll go over what information to place where.
Once you have your Merge Production Key, insert this under Authorization, selecting Bearer Token as the Type.
Here, we are inserting the key as a variable, calling it api-key:
The token will now be automatically included under "Headers" with a "Bearer" prefix, as shown:
Add the Merge Linked Account Token as a header under the name "X-Account-Token". Note that there will be a number of auto-generated headers in this section.
Type the URL for the Merge endpoint you want to test. Adjust the method based on whether you're sending a GET or POST request. For this example, we're testing the GET /candidates endpoint under the ATS (Applicant Tracking System) category. This will fetch information about candidates on the particular ATS application.
After configuring the request, click Send. If successful, the response will return a body as shown:
A 200 status code is typically used to indicate a successful HTTP response. Client errors are often indicated by 4xx response codes, while 5xx response codes are used for server errors.
Note that the response body varies by API and by request. You can refer to our docs to check out the relevant fields for each object and endpoint.
Until this point, we've been dealing with GET requests, which are for reading data. POST requests allow you to write data to the server. These are used to create different resources depending on the category, such as applications and candidates on ATS applications, or employees and benefits on HRIS platforms.
One area that is often crucial for constructing successful POST requests is permissions. Many APIs (currently, several of our ATS integrations) require users to have particular access roles (admin, manager, etc.) in order to write to the server. Merge's remote_user_id field is used to pass through the user's ID for APIs that require access roles to be included with the request.
If you'd like to look at the available users and their access roles, you can send a GET request to the /users endpoint, which you can learn more about in our docs:
The remote user ID should be passed through as a query parameter, under the "Params" section. Insert a key-value pair with the key named remote_user_id. This will automatically include the field and its value in the API URL (query parameters have a ? right before the field name to help with parsing the URL):
Another key aspect of sending POST requests is including a JSON payload of the data you want to write to the server, forming the request body. This can be inserted under the Body tab. 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.
You can refer to our docs to see the schema for the specific object you are dealing with. For step-by-step instructions on using Merge's POST endpoints, refer to our Guide.
Now you should be all set to test your integrations. If you have any questions, please contact us at [email protected] and we'll be happy to help you configure your tests.