Getting started

Follow this guide to exercise the full Connect partner flow against the stub vendor in develop or staging. The stub is disabled in production.

Base URL: Examples use https://connect.humanly.io. Replace with https://api.dev.qualifi.hr if your partner integration uses the legacy domain — paths are identical.

Prerequisites

A partner master API key with accounts scope (minted in Eucalyptus Connect Partners).
Access to develop or staging (NODE_ENV must allow the stub vendor).
A valid Humanly interview ID in the target org (for the stub order step).

Step 1 — Provision a customer account

Use your partner master key. Save accountId and customerApiKey from the response — the customer key is shown once on first provision.

cURL
JavaScript
Python

export BASE='https://connect.humanly.io'
export PARTNER_MASTER_KEY='qapi_your_partner_master_key'
export EXTERNAL_ID="partner-customer-$(date +%s)"

curl -s -X POST "$BASE/connect/accounts" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $PARTNER_MASTER_KEY" \
  -H 'x-request-id: connect-quickstart-1' \
  -d "{
    \"externalId\": \"$EXTERNAL_ID\",
    \"name\": \"Acme Corp Quickstart\",
    \"timezone\": \"America/New_York\"
  }" | jq

export CUSTOMER_KEY='<customerApiKey from 201 response>'

const base = 'https://connect.humanly.io';
const partnerMasterKey = 'qapi_your_partner_master_key';

const response = await fetch(`${base}/connect/accounts`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': partnerMasterKey,
    'x-request-id': 'connect-quickstart-1'
  },
  body: JSON.stringify({
    externalId: `partner-customer-${Date.now()}`,
    name: 'Acme Corp Quickstart',
    timezone: 'America/New_York'
  })
});

const body = await response.json();
const customerKey = body.data?.customerApiKey;

import requests

base = 'https://connect.humanly.io'
partner_master_key = 'qapi_your_partner_master_key'

response = requests.post(
    f'{base}/connect/accounts',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': partner_master_key,
        'x-request-id': 'connect-quickstart-1',
    },
    json={
        'externalId': f'partner-customer-{int(__import__("time").time())}',
        'name': 'Acme Corp Quickstart',
        'timezone': 'America/New_York',
    },
)

customer_key = response.json().get('data', {}).get('customerApiKey')

Expected 201 Created with customerApiKey. See Account provisioning for idempotent reconnect and disconnect flows.

Step 2 — Connect the stub vendor

Switch to the customer API key (integrations scope).

cURL

# Requires BASE and CUSTOMER_KEY from Step 1
curl -s -X POST "$BASE/connect/stub/integrations" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $CUSTOMER_KEY" \
  -H 'x-request-id: connect-quickstart-2' \
  -d '{
    "config": {
      "apiKey": "stub-test-vendor-key"
    }
  }' | jq

Expected 201 with integrationId, type: StubVendor, and healthy: true. Details in Standardized vendor endpoints.

Step 3 — Health check

cURL

# Requires BASE and CUSTOMER_KEY from Step 1
curl -s "$BASE/connect/stub/health" \
  -H "x-api-key: $CUSTOMER_KEY" \
  -H 'x-request-id: connect-quickstart-3' | jq

Expected 200 with data.healthy: true. Platform liveness (no auth) is GET /connect/health.

Step 4 — Place a stub order

Requires a real interviewId UUID from the provisioned org.

cURL

# Requires BASE and CUSTOMER_KEY from Step 1
export INTERVIEW_ID='<humanly-interview-uuid>'
export ORDER_REF="stub-order-$(date +%s)"

curl -s -X POST "$BASE/connect/stub/order" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $CUSTOMER_KEY" \
  -H "x-request-id: connect-quickstart-4" \
  -d "{
    \"requesterRefId\": \"$ORDER_REF\",
    \"candidateId\": \"candidate-$ORDER_REF\",
    \"firstName\": \"Jane\",
    \"lastName\": \"Doe\",
    \"email\": \"jane.doe@example.com\",
    \"interviewId\": \"$INTERVIEW_ID\",
    \"resultsURL\": \"https://example.com/results\"
  }" | jq

Expected 201 with invite URL in the Connect order envelope.

Next steps

Permission scopes

When to use accounts vs integrations keys

Error envelope

Parse Connect error codes

Request tracing

Correlate calls with x-request-id

Get Started

Partner lifecycle

Data operations

Build

Prerequisites

Step 1 — Provision a customer account

Step 2 — Connect the stub vendor

Step 3 — Health check

Step 4 — Place a stub order

Next steps

Permission scopes

Error envelope

Request tracing

​Prerequisites

​Step 1 — Provision a customer account

​Step 2 — Connect the stub vendor

​Step 3 — Health check

​Step 4 — Place a stub order

​Next steps

Permission scopes

Error envelope

Request tracing

Prerequisites

Step 1 — Provision a customer account

Step 2 — Connect the stub vendor

Step 3 — Health check

Step 4 — Place a stub order

Next steps