Agency Sub-Accounts API

The Sub-Accounts API enables programmatic tenant provisioning, initial star gatekeeper configuration, and automated queueing of complimentary physical smart NFC countertop stand shipments.

POST/api/v1/agency/subaccounts

Creates an isolated SMB sub-account tenant under your parent Agency organization, assigns a slug, initializes review redirection settings (minimum score threshold 4), and registers an initial fulfillment record in hardwareOrders.

Authentication

Authorization: Bearer aev_live_...

Rate Limit / Quota

Up to 100 sub-accounts per Agency plan

Request Body Attributes

The request body must be serialized as a JSON object with Content-Type: application/json.

Field	Type	Required	Description
name	string	Yes	Business name of the client organization (e.g. "Beacon Dental Care").
adminEmail	string	Yes	Primary notification email address for the business owner.
shippingName	string	Yes	Attention / recipient name printed on the physical stand parcel.
shippingAddress	string	Yes	Street address and suite number for physical courier delivery.
shippingCity	string	Yes	Destination city for physical shipment.
shippingState	string	Yes	2-letter state or province abbreviation (e.g. "CA", "TX").
shippingZip	string	Yes	Postal or ZIP code for shipment courier routing.
googleReviewUrl	string	Optional	Direct URL to the business's Google Review prompt (for ratings ≥ 4).
placeId	string	Optional	Google Place ID. If provided, automatically generates the official Google review write URL.
websiteUrl	string	Optional	Client's primary company website destination.

Code Implementation Samples

Provision Sub-Account Example

curl -X POST https://aevloc.com/api/v1/agency/subaccounts \
  -H "Authorization: Bearer aev_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Beacon Dental Care",
    "adminEmail": "[email protected]",
    "shippingName": "Beacon Dental (Attn: Reception)",
    "shippingAddress": "450 Sutter Street, Suite 800",
    "shippingCity": "San Francisco",
    "shippingState": "CA",
    "shippingZip": "94108",
    "googleReviewUrl": "https://search.google.com/local/writereview?placeid=ChIJN1t_tDeuEmsRUsoyG83frY4",
    "websiteUrl": "https://beacondental.com"
  }'

Response Specifications

201 CreatedSuccessful Provisioning

{
  "success": true,
  "data": {
    "organizationId": "0191f6a2-8b4e-7210-9831-e6e8c1a892b1",
    "name": "Beacon Dental Care",
    "slug": "beacon-dental-care",
    "funnelUrl": "https://aevloc.com/review?org=0191f6a2-8b4e-7210-9831-e6e8c1a892b1",
    "hardwareOrder": {
      "id": "0191f6a2-8b51-789a-bc32-11449900aabb",
      "type": "initial",
      "status": "pending",
      "recipient": "Beacon Dental (Attn: Reception)"
    }
  }
}

Status Code Matrix

401 Unauthorized

Missing, malformed, or revoked Agency Bearer API Key.

403 Forbidden

Sub-account quota reached (maximum 100 client organizations).

422 Unprocessable

Missing required fields or invalid shipping address parameters.

400 Bad Request

Malformed or unparseable JSON request body.

GoHighLevel Guide Webhook Troubleshooting