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.
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).
# 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 # 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.
# 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
