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

# Provision a GoHighLevel account through the API

> Create or retrieve the Assistable account for a location authorized under your agency.

Use this path to automate GHL account onboarding after your workspace has authorized the agency. Use the [v3 authentication guide](/v3/authentication) for key creation and handling.

## Prerequisites

* A **workspace-level** API key with `subaccounts:create`. A key restricted to selected subaccounts cannot create accounts.
* Completed GHL agency OAuth for that workspace.
* A location your agency is authorized to install.

## Create or retrieve the account

Send the location ID alone as the creation mode:

```bash theme={null}
curl https://api.assistable.ai/v3/subaccounts \
  -H "Authorization: Bearer $ASSISTABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"location_id":"YOUR_GHL_LOCATION_ID"}'
```

Do not include `name` in this request: `location_id` selects GHL provisioning, while `name` selects [Direct provisioning](/direct/provisioning). Supply exactly one.

A new account returns `201`; an existing active account in the same workspace returns `200`. Save the returned account ID. Retrying the same location does not create a second account. An archived/deleted account may be reactivated by this operation, so confirm that restoration is intended before sending it.

## Request and response reference

| Request field | Accepted value |
| - | - |
| `location_id` | Nonempty GHL location ID. Required for this guide's GHL provisioning mode. |
| `name` | Nonempty display name for Direct provisioning. Omit it when supplying `location_id`. |

There is no default creation mode: sending both fields or neither is invalid. The workspace comes from the API key, not a customer name or location label.

The successful response's account data contains:

| Field | Meaning for GHL provisioning |
| - | - |
| `id` | Assistable subaccount ID to retain for later requests |
| `name` | Account display name; inspect it because GHL detail loading is best effort |
| `integrationType` | Account integration type identifying its GHL connection |
| `locationId` | Connected GHL location identifier |
| `integrationId` | `null` in this GHL provisioning response |
| `webhookUrl` | `null`; the inbound listener URL is for Direct accounts |
| `webhookSecret` | `null`; GHL provisioning does not return a Direct webhook secret |
| `createdAt` | Account creation timestamp; retrieving an existing account does not create a new one |

HTTP `201` means a new account was created. HTTP `200` means an existing account was returned or restored. `workspace_forbidden` is `403`, `ghl_not_connected` and `location_conflict` are `409`, `location_not_found` is `404`, and an invalid creation mode is `400`. Authentication, missing scope and rate-limit failures follow the [v3 errors reference](/v3/errors).

## Verify onboarding

Read the returned account details and open that account in Assistable. Confirm its location and run the GHL connection check. Business-detail loading is best effort: provisioning can succeed even if GHL details could not be loaded, so inspect the name and timezone before deploying an assistant.

| Error | Action |
| - | - |
| `workspace_forbidden` | Use a workspace-level key, not a subaccount-restricted key |
| `ghl_not_connected` | Authorize the agency in this workspace |
| `location_not_found` | Check agency authorization and the location ID |
| `location_conflict` | Resolve the location's existing ownership in another workspace |
| `validation_error` | Supply exactly one of `location_id` or `name` |

See the [v3 guide](/v3/introduction), [errors](/v3/errors), and [account management](/v3/guides/accounts/manage-clients).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.