> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humanly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

> Quickstart — provision a customer, connect stub vendor, health check, and order

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

<Note>
  **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.
</Note>

## Prerequisites

1. A **partner master API key** with `accounts` scope (minted in Eucalyptus Connect Partners).
2. Access to **develop** or **staging** (`NODE_ENV` must allow the stub vendor).
3. 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.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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>'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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;
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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')
    ```
  </Tab>
</Tabs>

Expected **201 Created** with `customerApiKey`. See [Account provisioning](/connect/account-provisioning) for idempotent reconnect and disconnect flows.

## Step 2 — Connect the stub vendor

Switch to the **customer API key** (`integrations` scope).

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    # 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
    ```
  </Tab>
</Tabs>

Expected **201** with `integrationId`, `type: StubVendor`, and `healthy: true`. Details in [Standardized vendor endpoints](/connect/standardized-vendor-endpoints).

## Step 3 — Health check

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    # 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
    ```
  </Tab>
</Tabs>

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.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    # 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
    ```
  </Tab>
</Tabs>

Expected **201** with invite URL in the Connect order envelope.

## Next steps

<CardGroup cols={2}>
  <Card title="Permission scopes" icon="key" href="/platform/permission-scopes">
    When to use `accounts` vs `integrations` keys
  </Card>

  <Card title="Error envelope" icon="triangle-exclamation" href="/platform/error-envelope">
    Parse Connect error codes
  </Card>

  <Card title="Request tracing" icon="route" href="/platform/request-tracing">
    Correlate calls with `x-request-id`
  </Card>
</CardGroup>