Users API Documentation
Overview
The Users API lets you search users in your accessible scope and create new users with the same
account-bound permissions your web app enforces. GET /api/v1/users searches users,
while POST /api/v1/users creates a new user. The caller's role determines which
account can be attached to the new user.
Authorization summary
- Publisher users can only create users in their own publisher.
- Agency users can only create users in their own agency.
- Network users can only create users in their own network.
-
Only one linked-account target is allowed per request:
agency_id,network_id.
MCP Server
You can also search users through the MCP server using the named search_users tool,
or create users through the named refer_user or create_referred_user tools, or the generic api_request bridge.
Endpoint
Search users
GET/api/v1/users
Search users within the caller's accessible scope using q, email, name, or account filters.
Create user
POST/api/v1/users
Create a user within the caller's allowed account scope.
Authentication
X-Api-Key: YOUR_API_KEY
Required for every request.
agency_id, network_id,
the endpoint forces publisher_id to the HiEnergy publisher in the saved record.
API Playground
Use the live test cards for search, then copy the request bodies below for user creation and MCP referral flows. Sign in to enable live testing with your API key.
| Action | Method | Endpoint | Description |
|---|---|---|---|
| Search by query | GET |
/api/v1/users?q=alice |
Search users by name, email, or account filters. |
| Search by email | GET |
/api/v1/[email protected] |
Find a single user by email address. |
| Search by name | GET |
/api/v1/users?name=Alice%20Smith |
Search by the user's display name. |
| Create user | POST |
/api/v1/users |
Create a user in your allowed publisher, agency, or network scope. |
| Refer user alias | POST |
/api/v1/users |
MCP-friendly alias for creating a referred user. |
GET /api/v1/users?q=alice
v1
Search users with a query string.
GET /api/v1/[email protected]
v1
Search users by email.
GET /api/v1/users?name=Alice%20Smith
v1
Search users by display name.
Create user body
Use this on POST /api/v1/users when you want to create a user in the allowed scope.
{
"user": {
"email": "[email protected]",
"name": "New Publisher User",
"publisher_id": 42,
"given_name": "New",
"family_name": "User"
}
}MCP refer_user payload
Use this inside /mcp when you want the shorter alias for referred-user creation.
{
"jsonrpc": "2.0",
"id": 52,
"method": "tools/call",
"params": {
"name": "refer_user",
"arguments": {
"user": {
"email": "[email protected]",
"given_name": "MCP",
"family_name": "Referred",
"publisher_id": 42
}
}
}
}Scope rules
| Caller | Allowed target | Notes |
|---|---|---|
| Publisher user | Own publisher_id only |
agency_id and network_id are cleared. Trying another publisher returns 403 Forbidden. |
| Agency user | Own agency_id only |
publisher_id is forced to HiEnergy. Trying another agency returns 403 Forbidden. |
| Network user | Own network_id only |
publisher_id is forced to HiEnergy. Trying another network returns 403 Forbidden. |
Request body
Send a top-level user object. Only email is typically required in practice, but normal user validations still apply.
| Field | Type | Who can send it | Description |
|---|---|---|---|
email | string | All callers | User email address. |
password | string | All callers | Optional password for standard user creation flows. |
name | string | All callers | Full display name. |
given_name | string | All callers | First name. |
family_name | string | All callers | Last name. |
publisher_id | integer | All callers | For non-admin publisher users this must match their own publisher. Ignored or overridden in linked-account flows. |
agency_id | integer | Agency callers | Target agency user scope. Must be the caller's own agency. |
network_id | integer | Network callers | Target network user scope. Must be the caller's own network. |
Examples
Publisher user creates a user in the same publisher
curl -X POST "https://app.hienergy.ai/api/v1/users" \
-H "Content-Type: application/json" \
-H "X-Api-Key: YOUR_API_KEY" \
-d '{
"user": {
"email": "[email protected]",
"publisher_id": 42,
"name": "New Publisher User"
}
}'Agency user creates another user in the same agency
curl -X POST "https://app.hienergy.ai/api/v1/users" \
-H "Content-Type: application/json" \
-H "X-Api-Key: YOUR_API_KEY" \
-d '{
"user": {
"email": "[email protected]",
"name": "Agency Teammate"
}
}'The endpoint automatically applies the caller's agency_id and forces publisher_id to HiEnergy.
Successful response
A successful request returns 201 Created with a compact user payload.
{
"data": {
"id": 123,
"type": "user",
"attributes": {
"email": "[email protected]",
"name": "New Publisher User",
"given_name": null,
"family_name": null,
"admin": false,
"publisher_id": 42,
"agency_id": null,
"network_id": null
}
}
}Error cases
| Status | When it happens |
|---|---|
400 Bad Request | You provide more than one linked-account target from agency_id, network_id. |
401 Unauthorized | The API key is missing or invalid. |
403 Forbidden | The caller tries to create a user outside their own publisher, agency, or network scope. |
422 Unprocessable Entity | Model validation fails, for example invalid admin email/auth configuration. |
Example bad-request response
{
"error": {
"code": "BAD_REQUEST",
"message": "Provide only one of agency_id and network_id",
"timestamp": "2026-03-16T10:15:00Z",
"request_id": "abc123"
}
}Example validation response
{
"errors": [
"Admin users must use a Google/GSuite identity"
]
}FAQ
agency_id, network_id.
publisher_id, with no agency, network, or advertiser attached.