> This page is for Unified. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # Testing Merge's Unified API via Postman > How to set up a Postman collection for Merge API testing, including auth headers and example requests. --- ## Overview [Postman API](https://www.postman.com/) 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. --- ## Finding your authentication keys 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: #### [Authentication](/merge-unified/hris/merge-api-basics/authentication) Authenticate your requests to the Merge API --- ## Configuring Postman There are a few ways to get started: 1. (Recommended) Use Merge's public Postman workspace 2. Import Merge's APIs into Postman using OpenAPI schemas 3. Manual setup ### Option 1 (Recommended) - Use Merge's public Postman workspace Run in Postman You'll be able to fork our collections and/or put in your access tokens as environment variables and get going quickly. ### Option 2 - Import Merge's APIs into Postman using OpenAPI schemas 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: ![Import OpenAPI schema](/_fern-img/2abbc3e4b0e0b01b83e13d71ed7561b6ea19c94d1781708572beed71ba48d020.webp) Endpoints will be imported as folders, and include example responses: ![Imported endpoints](/_fern-img/adb30d97c3265556c81ae88c66a8ba442ca2fd8ac927b7c834d1dad0b0f72fda.webp) ### Option 3 - Manual setup 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`: > **Note** > > Variables are useful for storing and reusing values. Variable scopes include: > > * **Global:** accessed between collections, requests, test scripts and environments; available throughout a workspace > * **Collection:** independent of environment > * **Environment:** can help to differentiate between testing and production ![Bearer token configuration](/_fern-img/8502fa7e45129a0aac41ebbad4065cc8b523ffcfae04f6060d5776baeb933402.webp) The token will now be automatically included under "Headers" with a "Bearer" prefix, as shown: ![Auto-generated bearer header](/_fern-img/231f965a8b31f80065232ad2b576d33a1b02cbc96b9235b33ad9f0a23f2fd68f.webp) 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. ![X-Account-Token header](/_fern-img/2875364146e4782460e0700311e5c217fcb71e373928ed0da19adb45a18557a0.webp) 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. > **Note** > > The schema for Merge API requests is: `https://api.merge.dev/api//`. The syntax can be found in our [Docs](/). --- ## Sending requests to Merge API endpoints After configuring the request, click **Send**. If successful, the response will return a body as shown: ![Successful 200 response](/_fern-img/00cededb9780f72e3ed731b89e3374d8528463230cd4dd2b0e42c190fe8bfbc7.webp) 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. --- ## Writing data with Merge's POST endpoints 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](/): ![GET users request](/_fern-img/cc9e4998cfa1e7ef6f3e76fddf24509bab812cc3641caacaeff84485e2f7dd0a.webp) > **Note** > > Note that the field you'll want to use is `id`, as that is the Merge ID you will be passing as your remote user ID. Be sure not to confuse `remote users` with `remote IDs`. 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): ![Remote user ID param](/_fern-img/a88d40a71e34731736f405fc3722835a290906806763ce592f981c03e2d7e766.webp) 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. ![POST request body](/_fern-img/8a8610fe1fd8b06ffd6cf1e1c55b06055916136f4a732480709d449740e005ad.webp) 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](/guides/testing-via-postman). --- Now you should be all set to test your integrations. If you have any questions, please contact us at [hello@merge.dev](mailto:hello@merge.dev) and we'll be happy to help you configure your tests.