Overview

This guide walks through the recommended way to create a job application — and, if needed, the underlying candidate — in your customers' ATS using a single call to Merge's POST /applications endpoint.

Starting in October 2024, POST /applications accepts candidate information directly in the request body. This lets you power "apply" and "submit candidate" experiences with one request instead of two, while keeping the previous two-step flow fully supported.

When to use the simplified flow

Your product likely has a workflow where an end user (or your application acting on their behalf) submits a candidate to a job in your customer's ATS. Before October 2024, this required two sequential calls:

1. Create the candidate via POST /candidates.

2. Create the application via POST /applications, referencing the candidate created in step 1.

With the updated endpoint, you can send the candidate object nested inside the application request body. Merge will:

• Create the candidate if one does not already exist in the customer's ATS.

• Attach the new application to the existing candidate if one is already present.

Best practice is to migrate to the single-call flow for supported integrations. It reduces request volume, removes a class of "orphaned candidate" errors, and simplifies your error handling.

Instructions

Step 1: Confirm the integration is supported

The simplified POST /applications behavior is available for the following ATS integrations:

• Ashby

• Asymbl

• Avature

• BambooHR

• Bullhorn

• Bullhorn Recruitment Cloud

• Clockwork

• Comeet

• Cornerstone TalentLink

• Crelate

• Eploy

• Greenhouse

• Harbour ATS

• iCIMS

• JazzHR

• JobAdder

• Jobvite

• Lever

• Oracle Taleo

• SAP SuccessFactors

• SmartRecruiters

• Taleez

• Teamtailor

• UKG Pro Recruiting

• Workday

For integrations not on this list, continue using the two-step POST /candidates then POST /applications flow.

Step 2: Build the request body

Send the candidate as a nested object inside model, alongside the job and current_stage references the application needs. A typical request body looks like:

{
    "model": {
        "candidate": {
            "first_name": "Jane",
            "last_name": "Doe",
            "email_addresses": [
                {
                    "value": "[email protected]",
                    "email_address_type": "PERSONAL"
                }
            ],
            "phone_numbers": [
                {
                    "value": "9293388299",
                    "phone_number_type": "MOBILE"
                }
            ],
            "attachments": [
                {
                    "file_name": "Jane Doe Resume.pdf",
                    "file_url": "https://pdfobject.com/pdf/sample.pdf",
                    "attachment_type": "RESUME"
                }
            ],
            "applications": []
        },
        "job": "ecbadbed-4ff8-4191-9f8b-f31a9359ccca",
        "current_stage": "6ecfc3e2-563f-4894-b2b3-4f69bdc0856f"
    }
}

• candidate — the candidate fields you would have sent to POST /candidates. Merge uses these to look up or create the candidate.

• job — the Merge Job ID the application is for. Fetch this from GET /jobs.

• current_stage — the Merge JobInterviewStage ID representing where the application should start. Fetch from GET /job-interview-stages.

Step 3: Surface job and stage selection to your customer

Best practice is to give your end user (or your customer's recruiter) a UI to choose the job and current_stage rather than hard-coding them. A typical pattern:

1. After the customer links their ATS, fetch their jobs from GET /jobs and store the IDs you need.

2. For each job, fetch the available stages from GET /job-interview-stages so your UI can show the correct "starting stage" options.

3. Pass the selected IDs into the POST /applications request body shown in Step 2.

Step 4: Handle the response

POST /applications returns the created Application along with the resolved Candidate. Persist both IDs so subsequent updates (e.g., stage transitions via PATCH /applications/{id}) can reference them without another lookup.

If your product previously stored a candidate ID after POST /candidates, update your data model to capture the candidate ID returned by POST /applications instead.

Migrating from the two-step flow

If you already have a working POST /candidates + POST /applications integration:

• Migration is optional — no action is required, the two-step flow continues to work.

• When you do migrate, you can ship the change endpoint-by-endpoint. The simplified flow is per-request, so older code paths can keep using two calls while new code paths use one.

• Test against at least one of your top integrations first (e.g., Greenhouse or Lever) before rolling out broadly.

Questions

If you'd like to request support for an additional integration, or have questions about migrating, please contact your customer success manager or email [email protected].