Skip to main content
Use this guide to seamlessly connect InterviewFlowAI with your existing Applicant Tracking Systems (ATS), CRMs, or internal tools. Proper integration ensures automated candidate ingestion, two-way data syncing, and real-time updates, creating a frictionless experience for both your hiring team and your candidates.

​
How integrations work

In the Integrations flow, you configure core communication channels between InterviewFlowAI and your external systems:
API / FeatureDescription
Ingestion APIPush candidate data into InterviewFlowAI programmatically to trigger interview invitations.
Fetch APIRetrieve candidate lists, specific interview details, and filter records directly from our system.
Patch APIUpdate custom fields and sync statuses back to candidate records in InterviewFlowAI.
1

Generate your API key

Before setting up any connections, you must authenticate your requests.
  1. Navigate to the API Keys section in your main dashboard settings.
  2. Click Generate to create a new secure API key.
Requirement: You must include this API key in the headers of all your API requests (Ingestion, Fetch, and Patch) to authenticate successfully. Keep this key secure.
2

Access Interviewer-specific integrations

Integrations are scoped to specific Interviewers to ensure candidates are routed to the correct interview flow.
  1. Select your target Interviewer from the main dashboard.
  2. Click on View Interviews.
  3. Click on the Integrations tab.
3

Configure the Ingestion API

The Ingestion API allows you to programmatically add candidates to a specific Interviewer pipeline.

​
Payload structure

FieldTypeRequiredDescription
interviewerIdstring✅ YesThe unique ID of the Interviewer to ingest candidates into.
statusstring❌ Noshortlisted or draft. Controls onboarding experience.
skillsarray❌ No["nodejs", "aws", "mongodb"] array of skills to generate custom questions.
dataarray✅ YesArray of candidate objects.
data[].namestring✅ YesCandidate’s full name.
data[].emailstring✅ YesCandidate’s email address.
data[].additionalFieldsobject❌ NoCustom key-value fields to tag against the candidate (e.g. scores, flags).
data[].metadataobject❌ NoExternal reference data (e.g. ATS ID, phone number). Not used in scoring.

​
Status routing

StatusBehavior
shortlistedCandidate bypasses the application form and is redirected straight to the interview lobby (requires Resume Screening and Screening Questions to be disabled).
draftCandidate must fill out the application form. Your team will then need to manually shortlist them from the dashboard.

​
Default behavior (when status is omitted)

Interviewer VisibilityDefault Status
Public Interviewershortlisted
Private Interviewerdraft

​
Example request

curl -X POST "https://api.interviewflowai.com/api/external/ingest/candidates" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -d '{
    "status": "shortlisted",
    "interviewerId": "304c0cfb-324f-4b2c-ac89-c93725c00399",
    "data": [
      {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "skills": ["nodejs", "aws", "mongodb"],
        "additionalFields": {
          "Manual Score": 72,
          "isSynced": "true"
        },
        "metadata": {
          "External ID": "candidate_12345",
          "Phone": "+1-555-123-4567"
        }
      }
    ]
  }'
Best Practice: Trigger this API call automatically when a candidate reaches a specific stage in your ATS (e.g. “Phone Screen” or “AI Interview”).
4

Retrieve data with the Fetch API

The Fetch API allows you to pull candidate and interview data back into your own internal systems. All fetch requests are POST requests with a JSON body.

​
Request body fields

FieldTypeRequiredDescription
interviewerIdstring✅ YesThe unique ID of the Interviewer to fetch candidates from.
pagenumber❌ NoPage number for paginated results.
limitnumber❌ NoNumber of results per page.
interviewIdstring❌ NoFetch a single candidate by their unique interview ID.
additionalFieldsobject❌ NoFilter candidates by custom field values (see filtering rules below).

​
1. Paginated fetch

Retrieve a paginated list of candidates for a specific Interviewer.
curl -X POST "https://api.interviewflowai.com/api/external/fetch/candidates" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -d '{
    "interviewerId": "9786b00b-d110-454f-9e6f-1732daec8916",
    "page": 1,
    "limit": 20
  }'

​
2. Single candidate fetch

Look up a specific candidate using their unique interview ID.
curl -X POST "https://api.interviewflowai.com/api/external/fetch/candidates" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -d '{
    "interviewerId": "9786b00b-d110-454f-9e6f-1732daec8916",
    "interviewId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }'

​
3. Custom field filters

Filter your candidate list based on values in additionalFields. Filtering rules:
  • Numeric values: Returns candidates where the field value is ≥ the specified number (e.g. "score": 50 returns all candidates with score 50 or above).
  • String values: Returns candidates where the field value exactly matches the string (e.g. "review": "yes").
curl -X POST "https://api.interviewflowai.com/api/external/fetch/candidates" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -d '{
    "interviewerId": "9786b00b-d110-454f-9e6f-1732daec8916",
    "page": 1,
    "limit": 20,
    "additionalFields": {
      "score": 50,
      "review": "yes"
    }
  }'
5

Update records with the Patch API

The Patch API allows you to update custom fields for a specific interview record. This is highly useful for syncing data, scores, or review flags from your external tools back into InterviewFlowAI.
curl -X PATCH "https://api.interviewflowai.com/api/interview/custom-fields" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -d '{
    "interviewId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "candidateAdditionalFields": {
      "score": 72,
      "review": "yes",
      "isSynced": true
    }
  }'