Account provisioning - Humanly Developer Docs

Partner-facing account lifecycle at /connect/accounts. Requires a partner master API key with the accounts scope. Customer keys (integrations scope) cannot call these routes.

This endpoint requires the accounts scope. Org-scoped Gather keys and customer Connect keys return 403 Forbidden.

Base path: {BASE_URL}/connect/accounts — not /qsi/connect/accounts.

Authentication

x-api-key

string

required

Partner master API key with accounts scope, linked to a Connect partner (connectPartnerId).

x-request-id

string

Optional correlation ID returned in meta.requestId. See Request tracing.

Provision account

Find-or-create a customer organization for your partner. Endpoint: POST /connect/accounts

externalId

string

required

Your stable customer identifier (scoped per Connect partner).

name

string

required

Organization display name. Must be globally unique when creating a new org.

timezone

string

IANA timezone (e.g. America/New_York). Optional; defaults if omitted.

Responses

HTTP	When	`customerApiKey` in response?
201	New org created	Yes — store securely; shown once
200	Same `externalId`, active key	No
200	Reconnect after disconnect	Yes — new key
409	`name` taken by a different org	—
403	Not a partner master key	—

cURL
JavaScript
Python

curl -s -X POST "https://connect.humanly.io/connect/accounts" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $PARTNER_MASTER_KEY" \
  -d '{
    "externalId": "partner-customer-123",
    "name": "Acme Corp",
    "timezone": "America/New_York"
  }'

const response = await fetch('https://connect.humanly.io/connect/accounts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': partnerMasterKey
  },
  body: JSON.stringify({
    externalId: 'partner-customer-123',
    name: 'Acme Corp',
    timezone: 'America/New_York'
  })
});

import requests

requests.post(
    'https://connect.humanly.io/connect/accounts',
    headers={'Content-Type': 'application/json', 'x-api-key': partner_master_key},
    json={
        'externalId': 'partner-customer-123',
        'name': 'Acme Corp',
        'timezone': 'America/New_York',
    },
)

{
  "data": {
    "accountId": "uuid",
    "name": "Acme Corp",
    "externalId": "partner-customer-123",
    "connectStatus": "active",
    "customerApiKey": "qapi_customer_key_show_once",
    "isNew": true
  },
  "meta": {
    "requestId": "req_...",
    "timestamp": "2026-06-17T12:00:00.000Z"
  }
}

Get account

Endpoint: GET /connect/accounts/{accountId} Returns accountId, name, externalId, connectStatus (active | disconnected), and an integrations summary.

Disconnect account

Endpoint: DELETE /connect/accounts/{accountId} Revokes customer Connect API key(s). Does not delete the org or integration rows. Returns connectStatus: disconnected. Reconnect with another POST /connect/accounts using the same externalId to receive a new customerApiKey.

Customer key policy

Customer keys minted during provisioning have integrations scope only — use them for /connect/{vendor}/* routes, not for account provisioning.

Permission scopes — accounts vs integrations
Getting started — end-to-end stub flow
Standardized vendor endpoints — after provisioning

​Authentication

​Provision account

​Responses

​Get account

​Disconnect account

​Customer key policy

​Related

Authentication

Provision account

Responses

Get account

Disconnect account

Customer key policy

Related