API Integration Guide

Flowmingo exposes a lightweight REST surface so you can trigger interview invitations from your ATS, CRM, or internal tooling. This section explains how to create API keys and use them to call Flowmingo's integration APIs.

1. Prerequisites

• Workspace access: You need access to Settings -> Integrations -> API Keys in the company workspace.
• Interview set and/or project ID: Keep the UUID you will target (com_interview_set_id and/or com_project_id).
• CV file hosting (if sending CVs): Upload CVs to publicly accessible HTTPS storage (or signed URLs) that Flowmingo can fetch.

2. Request an API key

2.1 Open the API Keys panel

1. Sign in at https://team.flowmingo.ai.
2. Open your avatar menu -> Settings.
3. Go to Integrations -> API Keys.

2.2 Create a key

1. Click Create New Secret Key.
2. Provide Name and Description.
3. (Optional) add scopes such as Invite Candidates.
4. Click Generate.

You will receive a one-time secret with format like fl_live_abcd12345.<secret>. Copy and store it immediately. After creation, key values are masked (for example: fl_live_abcd12345.****).

2.3 Update metadata

Use Edit on an existing key to update:

• name
• description
• scopes
• status

2.4 Rotate or revoke

Delete a key to revoke access immediately, then create a new key and update your integrations.

2.5 Security notes

Store API keys in a secret manager (AWS Secrets Manager, GCP Secret Manager, 1Password, etc.). Never embed keys in frontend code, logs, or version control.

3. Invite candidates through the API

3.1 Endpoint & environments

3.2 Request payload

3.3 Sample request

curl -X POST https://apis.flowmingo.ai/company/integration/interview/candidate/invite/v1 \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: fl_live_abcd12345.n8G3zPNw9gWkK1Kj' \
  -d '{
    "com_interview_set_id": "019c5ea9-a792-7f0d-b671-4c3c1602094e",
    "candidates": [
      {
        "name": "Alex Doe",
        "email": "alex@example.com",
        "cv_link": "https://storage.googleapis.com/flowmingo-demo/cv/alex.pdf"
      }
    ],
    "invitation_message": "<p>Dear <b><span>{{candidate_name}}</span></b>,</p>
<p>We are excited to inform you that, after reviewing your application, we would like to invite you for a video interview for the position of <b>{{position_name}}</b> at <b>{{company_name}}</b>.</p>
<p>We look forward to discussing your qualifications further!</p>
<p>Link to interview: <a href=\"{{interview_link}}\">{{interview_link}}</a></p>
<p>Thank you.</p>
<p>Sincerely,<br/>
{{company_name}}
</p>",
    "send_invite": true
  }'

3.4 Sample response

The endpoint returns a response envelope with per-candidate results:

{
  "results": [
    {
      "email_address": "alex@example.com",
      "cv_link": "https://storage.googleapis.com/flowmingo-demo/cv/alex.pdf",
      "invitation": {
        "id": "019c5eb3-fb50-707b-9833-0862efa4b275",
        "email": "alex@example.com",
        "status_text": "pending"
      },
      "submission": {
        "id": "019c5eb4-55ab-76fc-90ec-98930c56a7bd",
        "status_text": "need_interview"
      }
    }
  ]
}

Error details are returned per candidate in fields such as error_message, invitation_error_message, application_error_message, submission_error_message, and candidate_entry_error_message.

Troubleshooting

• 401 / 403: API key is missing, malformed, deleted, inactive, expired, or (when scopes are configured) missing invite_candidates.
• 404 project/interview set: The UUID is invalid for your organization or the record is deleted.
• Validation errors: Ensure candidates is non-empty and each candidate has enough data for your desired flow (invite vs CV-entry queue).
• Duplicate ATS IDs in one payload: Ensure candidates[].ats_candidate_id values are unique per request.