Low-Code Integrations

Zapier Integration

Copy page

The Source Code for our Zapier integration is publicly available and can be found on our GitHub.

---

Prerequisites

Before setting up the HRMLESS Zapier integration, ensure you have:

1. Active HRMLESS Account

   • Sign up at https://hrmless.com
   • Verify your account and complete onboarding
   • Note your organization ID (automatically retrieved during authentication)

2. HRMLESS Credentials

   • Username
   • Password

3. Zapier Account

   • Free or paid Zapier account
   • Join our Zapier Integration Beta by clicking this link

4. API Access

   • HRMLESS API access is included with all account tiers
   • No additional API key required (uses OIDC authentication)

---

Quick Start (2 minutes)

Step 1: Access HRMLESS in Zapier

1. Log in to your Zapier account at https://zapier.com
2. Create a new Zap
3. Add a trigger (e.g. "schedule")

Step 2: Add a HRMLESS Zapier Action

1. Add a new action step
2. Search for "HRMLESS" in the app directory
3. Select the HRMLESS app
4. Choose an action (e.g., "Get All Positions")

Step 3: Authentication

1. Click "Sign in"
2. When the authentication window opens, log into your HRMLESS account

Step 4: Configure Action

1. Select any required fields (if applicable)
2. Test the action to ensure it works
3. Review output data
4. Publish action

---

HRMLESS uses session-based OAuth authentication with automatic token management. You never need to manually handle tokens or refresh credentials.

How It Works

1. Initial Authentication:

   • User provides username and password
   • Integration exchanges credentials for access token and refresh token
   • Organization ID is automatically retrieved and stored

2. Automatic Token Refresh:

   • Access tokens expire after a set period
   • Integration automatically refreshes tokens before expiration
   • No user action required

3. Secure Storage:

   • Credentials are encrypted by Zapier
   • Tokens are securely stored and never exposed
   • Organization ID is cached for all subsequent requests

Authentication Flow

Code
 
User Credentials (Username + Password / SSO)
         ↓
OAuth Token Exchange 
         ↓
Access Token + Refresh Token + Organization ID
         ↓
Stored in Zapier's Secure Vault
         ↓
Automatically Included in All API Requests

Troubleshooting Authentication

Problem: "Authentication failed. Please verify your credentials."

Solutions:

• Verify username and password are correct
• Ensure your HRMLESS account is active
• Check for extra spaces in username/password fields
• Try logging into your account and reseting your password.

Problem: "Token expired" or "Invalid token"

Solutions:

• This should be handled automatically by refresh token
• Try disconnecting and reconnecting your HRMLESS account in Zapier
• Contact support if issue persists

---

Available Actions

Position Management

📋 List All Positions

Action Key: orgPositionList

Retrieves all job positions created in your organization, including active, draft, and inactive positions.

Use Case: Display available positions in a dashboard, sync to job boards, or generate reports.

Input Fields: None (uses organization ID from authentication)

Output Fields: Returns array of position objects

Field	Type	Description
id	String (UUID)	Unique position identifier
name	String	Position title (e.g., "Senior Software Engineer")
state	String	Position status: active, draft, or inactive
department	String	Department name
location	String	Job location
min_score	Integer	Minimum interview score required to pass
role_description	String	Detailed job description
position_calender_link	String	Custom calendar link for this position
created_at	DateTime	Position creation timestamp
updated_at	DateTime	Last modification timestamp
agent_id	String	AI agent identifier (internal use)
questionaire	Array	Custom interview questions (see below)
created_by	Object	User who created the position

Questionnaire Structure:

Code
 
{
  "id": "2fa85f64-5717-4561-b3fc-2c963f66afa6",
  "name": "Question 1",
  "value": "Do you have experience with Python?"
}

Example Output:

Code
 
{
  "items": [
    {
      "id": "4fa85f64-5717-4562-b2fc-2c963f66afa6",
      "name": "Senior Software Engineer",
      "state": "active",
      "department": "Engineering",
      "location": "Remote",
      "min_score": 7,
      "role_description": "We're seeking an experienced software engineer...",
      "position_calender_link": "https://calendly.com/acme/senior-engineer",
      "created_at": "2025-06-26T19:10:20.269220Z",
      "updated_at": "2025-06-30T14:40:03.161801Z",
      "questionaire": [
        {
          "id": "2fa85f64-5717-4561-b3fc-2c963f66afa6",
          "name": "Question 1",
          "value": "Describe your experience with distributed systems"
        }
      ],
      "created_by": {
        "id": "8695dd58-c4cb-407b-bd59-a8ca2fb3286e",
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "[email protected]"
      }
    }
  ]
}

---

🔍 Get Position By ID

Action Key: orgPositionRead

Retrieves detailed information about a specific position.

Use Case: Get full position details before adding candidates or updating position information.

Input Fields:

Field	Type	Required	Description
position_id	String (UUID)	Yes	Position ID (dynamic dropdown populated from available positions)

Output Fields: Same as List All Positions (single object instead of array)

Candidate Management

📋 List Candidates in a Position

Action Key: orgPositionsRead

Retrieves all candidates associated with a specific position.

Use Case: Generate candidate reports, sync candidate lists to spreadsheets, or monitor pipeline health.

Input Fields:

Field	Type	Required	Description
position_id	String (UUID)	Yes	Position ID (dynamic dropdown)

Output Fields: Returns array of candidate objects

Field	Type	Description
id	String (UUID)	Unique candidate identifier
name	String	Candidate's full name
email	String	Candidate's email address
phone	String	Candidate's phone number
state	String	Current candidate status (see states below)
score	Integer	AI interview score (0-10)
feedback	String	AI-generated feedback
hired	Boolean	Whether candidate was hired
language	String	Interview language (e.g., "en", "es")
invited_at	DateTime	When invitation was sent
completed_at	DateTime	When interview was completed
created_at	DateTime	When candidate was added
updated_at	DateTime	Last modification timestamp
position_id	String (UUID)	Associated position ID
organization_id	String (UUID)	Organization ID
activity	Array	Candidate activity history

Candidate States:

• not_invited_yet - Candidate added but not contacted
• invited - Invitation email sent
• attempted - Started but didn't finish interview
• completed - Interview finished
• graded - AI scoring complete
• passed - Met minimum requirements
• rejected - Did not meet requirements
• calendar_link_sent - Follow-up scheduling link sent

Example Output:

Code
 
[
  {
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "name": "Alex Johnson",
    "email": "[email protected]",
    "phone": "+1-555-0142",
    "state": "passed",
    "score": 8,
    "feedback": "Strong technical knowledge, excellent communication skills...",
    "hired": false,
    "language": "en",
    "invited_at": "2025-11-01T10:00:00Z",
    "completed_at": "2025-11-02T14:30:00Z",
    "created_at": "2025-11-01T09:45:00Z",
    "updated_at": "2025-11-02T14:35:00Z",
    "position_id": "4fa85f64-5717-4562-b2fc-2c963f66afa6",
    "organization_id": "7e0eb807-2ede-460b-b564-7ad50660c21c"
  }
]

---

➕ Create Candidate For a Position

Action Key: orgPositionsCreate

Adds a new candidate to a position and automatically triggers the AI interview process.

Use Case: Automatically add applicants from job boards, forms, or your ATS to HRMLESS for screening.

Input Fields:

Field	Type	Required	Description
position_id	String (UUID)	Yes	Position ID (dynamic dropdown)
name	String	Yes	Candidate's full name
email	String	Yes	Candidate's email address
phone	String	Yes	Candidate's phone number
language	String	Yes	Interview language code (e.g., "en", "es", "fr")
state	String	No	Initial state (default: not_invited_yet)

Example Input:

Code
 
{
  "position_id": "4fa85f64-5717-4562-b2fc-2c963f66afa6",
  "name": "Maria Garcia",
  "email": "[email protected]",
  "phone": "+1-555-0198",
  "language": "en"
}

What Happens Next:

1. Candidate is added to the position
2. Candidate record is created with not_invited_yet status
3. You can trigger invitation manually or via automation
4. Candidate receives email with interview link
5. AI conducts interview when candidate clicks link
6. Results are automatically scored and available via API

---

🔍 Get Candidate Details

Action Key: orgPositionsCandidatesRead

Retrieves comprehensive information about a specific candidate, including interview scores, feedback, and activity history.

Use Case: Get candidate details before making hiring decisions or sending follow-up communications.

Input Fields:

Field	Type	Required	Description
position_id	String (UUID)	Yes	Position ID (dynamic dropdown)
candidate_id	String (UUID)	Yes	Candidate ID

Output Fields: Same as List Candidates (single object)

---

✏️ Update Candidate Details

Action Key: orgPositionsCandidatesUpdate

Updates candidate information, status, or hiring decision.

Use Case: Mark candidates as hired, update contact information, or change candidate status based on external workflow.

Input Fields:

Field	Type	Required	Description
position_id	String (UUID)	Yes	Position ID (dynamic dropdown)
candidate_id	String (UUID)	Yes	Candidate ID
name	String	No	Updated full name
email	String	No	Updated email address
phone	String	No	Updated phone number
state	String	No	Updated status
hired	Boolean	No	Hiring decision (true/false)
feedback	String	No	Additional feedback or notes

Example: Marking a Candidate as Hired

Code
 
{
  "position_id": "4fa85f64-5717-4562-b2fc-2c963f66afa6",
  "candidate_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "hired": true,
  "feedback": "Great fit for the team. Starting January 15."
}

---

🗑️ Delete Candidate

Action Key: orgPositionsCandidatesDelete

Permanently removes a candidate from a position.

Warning: This action cannot be undone. Interview data and history will be permanently deleted.

Use Case: Remove duplicate entries or candidates who requested data deletion (GDPR compliance).

Input Fields:

Field	Type	Required	Description
position_id	String (UUID)	Yes	Position ID (dynamic dropdown)
candidate_id	String (UUID)	Yes	Candidate ID to delete

Output:

Code
 
{
  "success": true
}

---

Interview Management

📊 Get Candidate Interview Details

Action Key: orgPositionsCandidatesInterview

Retrieves complete interview information including transcript, recording link, AI score, and detailed feedback.

Use Case: Review interview performance, access transcripts for hiring decisions, or archive interview data for compliance.

Input Fields:

Field	Type	Required	Description
position_id	String (UUID)	Yes	Position ID (dynamic dropdown)
candidate_id	String (UUID)	Yes	Candidate ID

Output Fields:

Field	Type	Description
id	String (UUID)	Interview ID
conversation_id	String	Unique conversation identifier
transcript_link	String (URL)	Link to full transcript
recording_link	String (URL)	Link to audio/video recording
start_time	DateTime	Interview start timestamp
end_time	DateTime	Interview end timestamp
graded_at	DateTime	When AI scoring completed
last_attempted_at	DateTime	Most recent attempt timestamp
ip_address	String	Candidate's IP address (privacy-aware)
location	String	Candidate's geographic location
interview_link	String (URL)	Original interview invitation link
status	String	Interview status: completed, attempted, not_started
score	Integer	AI-generated score (0-10)
feedback	String	Comprehensive AI feedback
interview_transcript	String	Complete interview transcript
candidate	String (UUID)	Candidate ID

Example Output:

Code
 
{
  "id": "b2c3d4e5-6789-01bc-def2-3456789012cd",
  "conversation_id": "conv_abc123451234512345",
  "transcript_link": "https://hrmless.com/transcripts/b2c3d4e5",
  "recording_link": "https://hrmless.com/recordings/b2c3d4e5",
  "start_time": "2025-11-02T14:00:00Z",
  "end_time": "2025-11-02T14:23:47Z",
  "graded_at": "2025-11-02T14:25:00Z",
  "last_attempted_at": "2025-11-02T14:00:00Z",
  "ip_address": "192.168.1.1",
  "location": "San Francisco, CA",
  "interview_link": "https://tiny.hrmless.io/abc123",
  "status": "completed",
  "score": 8,
  "feedback": "Candidate demonstrated strong problem-solving skills and clear communication. Technical knowledge is solid with 3+ years of relevant experience. Recommended for next round.",
  "interview_transcript": "AI: Welcome to your interview for Senior Software Engineer at Acme Corp...\nCandidate: Thank you, I'm excited to be here...",
  "candidate": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}

---

Data Structure Reference

Position Object

Code
 
{
  id: "4fa85f64-5717-4562-b2fc-2c963f66afa6",    // UUID, internally generated
  name: "Senior Software Engineer",              // String, required
  state: "active",                               // "active" | "draft" | "inactive"
  department: "Engineering",                     // String, optional
  location: "Remote",                            // String, optional
  min_score: 7,                                  // Integer 0-10, optional, defaults to 5
  role_description: "We're seeking...",          // String, optional
  position_calender_link: "https://...",         // URL, optional
  created_at: "2025-06-26T19:10:20.269220Z",     // ISO 8601 DateTime, internally generated
  updated_at: "2025-06-30T14:40:03.161801Z",     // ISO 8601 DateTime, internally generated
  agent_id: "string",                            // String, internal use
  questionaire: [                                // Array of questions
    {
      id: "2fa85f64-5717-4561-b3fc-2c963f66afa6",// UUID, internally generated
      name: "Question 1",
      value: "What's your experience?"
    }
  ],
  created_by: {                                  // User object, internally generated
    id: "8695dd58-c4cb-407b-bd59-a8ca2fb3286e",
    first_name: "Jane",
    last_name: "Smith",
    email: "[email protected]",
    phone: "234-234-1234",
    enabled: true
  }
}

Candidate Object

Code
 
{
  id: "a1b2c3d4-5678-90ab-cdef-1234567890ab",   // UUID, internally generated
  name: "Alex Johnson",                         // String, required
  email: "[email protected]",                      // String, required
  phone: "+1-555-0142",                         // String, required
  state: "passed",                              // Candidate state (see below)
  score: 8,                                     // Integer 0-10
  feedback: "Strong technical knowledge...",    // String, internally generated
  hired: false,                                 // Boolean
  communications: {},                           // Object, internally generated
  language: "en",                               // Language code, required
  invited_at: "2025-11-01T10:00:00Z",           // ISO 8601 DateTime, internally generated
  completed_at: "2025-11-02T14:30:00Z",         // ISO 8601 DateTime, internally generated
  created_at: "2025-11-01T09:45:00Z",           // ISO 8601 DateTime, internally generated
  updated_at: "2025-11-02T14:35:00Z",           // ISO 8601 DateTime, internally generated
  position_id: "4fa85f64-5717-4562-b2fc-...",   // UUID, internally generated
  organization_id: "7e0eb807-2ede-460b-...",    // UUID, internally generated
}

Candidate States

State	Description	Typical Next Actions
not_invited_yet	Candidate added, invitation pending	Send invitation email
invited	Invitation sent, awaiting response	Monitor for interview start
attempted	Started but didn't complete	Send reminder email
completed	Interview finished, awaiting grading	Wait for AI scoring
graded	AI scoring complete	Review results, decide next steps
passed	Met minimum requirements	Schedule follow-up interview
rejected	Did not meet requirements	Send rejection email
calendar_link_sent	Follow-up scheduling link sent	Wait for scheduling

Interview Object

Code
 
{
  id: "b2c3d4e5-6789-01bc-def2-3456789012cd",   // UUID, internally generated
  conversation_id: "conv_abc123",                // String, internally generated
  transcript_link: "https://...",                // URL, internally generated
  recording_link: "https://...",                 // URL, internally generated
  start_time: "2025-11-02T14:00:00Z",           // ISO 8601 DateTime, internally generated
  end_time: "2025-11-02T14:23:47Z",             // ISO 8601 DateTime, internally generated
  graded_at: "2025-11-02T14:25:00Z",            // ISO 8601 DateTime, internally generated
  last_attempted_at: "2025-11-02T14:00:00Z",    // ISO 8601 DateTime, internally generated
  ip_address: "192.168.1.1",                     // String, optional, internally generated
  location: "San Francisco, CA",                 // String, optional, internally generated
  interview_link: "https://tiny.hrmless.io/...", // URL, internally generated
  status: "completed",                           // String, internally generated
  score: 8,                                      // Integer 0-10, internally generated
  feedback: "Candidate demonstrated...",         // String, internally generated
  interview_transcript: "AI: Welcome...",        // String (full transcript), internally generated
  candidate: "a1b2c3d4-5678-90ab-cdef-..."      // UUID, internally generated
}

---

Troubleshooting

Authentication Issues

Problem: "Authentication failed. Please verify your credentials."

Cause: Invalid username or password.

Solution:

1. Double-check username (email) for typos
2. Verify password is correct (try logging in at hrmless.com)
3. Check for extra spaces before/after credentials
4. Reset password if necessary
5. Ensure account is active and verified

---

Problem: Token expired or keeps disconnecting

Cause: Refresh token may have expired or been revoked.

Solution:

1. Disconnect HRMLESS account in Zapier settings
2. Reconnect with fresh credentials
3. If issue persists, contact [email protected]

---

Action/Trigger Issues

Problem: "Position not found" or "Candidate not found"

Cause: Referenced resource doesn't exist or was deleted.

Solution:

1. Verify the ID is correct (UUIDs are case-sensitive)
2. Check if resource was deleted
3. Use "List" actions to find valid IDs
4. Ensure organization ID is correct

---

Problem: Dynamic dropdown not showing positions

Cause: No positions exist or API connection issue.

Solution:

1. Create at least one position in HRMLESS first
2. Refresh the dropdown in Zapier
3. Check authentication is still valid
4. Try disconnecting and reconnecting account

---

Problem: Candidate creation fails with validation error

Cause: Required fields are missing or formatted incorrectly.

Solution:

1. Ensure name, email, phone, and language are provided
2. Validate email format (must be valid email address)
3. Check phone number format (include country code)
4. Verify language code is supported (e.g., "en", "es")

---

Problem: "Organization ID not found"

Cause: Organization ID wasn't retrieved during authentication.

Solution:

1. Disconnect and reconnect HRMLESS account
2. During connection, ensure "Get Organization ID" completes
3. Check that your HRMLESS account has organization access
4. Contact support if issue persists

---

Error Codes

HTTP Code	Meaning	Solution
400	Bad Request - Invalid input data	Check field formats and required fields
401	Unauthorized - Invalid credentials	Reconnect your HRMLESS account
403	Forbidden - Insufficient permissions	Verify account permissions
404	Not Found - Resource doesn't exist	Verify IDs are correct
409	Conflict - Duplicate resource	Check if candidate/position already exists
500	Server Error - HRMLESS API issue	Retry in a few minutes, contact support if persistent

---

Best Practices

Security

1. Never share authentication credentials

   • Use Zapier's secure credential storage
   • Don't log or print access tokens
   • Rotate passwords regularly

2. Validate input data

   • Check email formats before sending to API
   • Sanitize phone numbers
   • Validate UUIDs

3. Handle sensitive data carefully

   • Interview transcripts may contain PII
   • Comply with GDPR/CCPA requirements
   • Implement data retention policies

---

End of Documentation

---

This README was last updated on November 13, 2025. For the latest version, visit https://github.com/hrmless/zapier

HRMLESS LLC. All rights reserved.