Create a user in your account scope

Operation

POST /users

Creates a user with strict account-scoped permissions. Non-admin API callers can only create users inside their own account scope: (1) their own publisher, or (2) their own agency, or (3) their own network. Admin callers can create users for any publisher and may also assign agency_id or network_id. The request must include exactly one account target when provided (publisher_id, agency_id, or network_id). If no target is provided, the API defaults to the caller's own scope. Non-admin calls always force admin=false for safety. The created user is automatically attributed to the API caller via referred_by.

Parameters

This operation does not define any parameters.

Request Body

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "user": {
            "type": "object",
            "properties": {
              "email": {
                "type": "string",
                "format": "email"
              },
              "password": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "given_name": {
                "type": "string"
              },
              "family_name": {
                "type": "string"
              },
              "admin": {
                "type": "boolean",
                "description": "Admin-only flag to create an admin user"
              },
              "auth0_uid": {
                "type": "string",
                "description": "Admin-only Auth0 UID"
              },
              "publisher_id": {
                "type": "integer"
              },
              "agency_id": {
                "type": "integer"
              },
              "network_id": {
                "type": "integer"
              },
              "advertiser_id": {
                "type": "integer"
              }
            },
            "required": [
              "email"
            ]
          }
        },
        "required": [
          "user"
        ]
      },
      "examples": {
        "non_admin_publisher_scope": {
          "summary": "Non-admin publisher scope request",
          "value": {
            "user": {
              "email": "[email protected]",
              "given_name": "New",
              "family_name": "User"
            }
          }
        },
        "admin_any_publisher": {
          "summary": "Admin assigning a specific publisher",
          "value": {
            "user": {
              "email": "[email protected]",
              "publisher_id": 123,
              "name": "Other Publisher User"
            }
          }
        },
        "admin_advertiser_user": {
          "summary": "Admin assigning an advertiser-linked user",
          "value": {
            "user": {
              "email": "[email protected]",
              "advertiser_id": 456,
              "name": "Advertiser User"
            }
          }
        }
      }
    }
  }
}

Responses

{
  "description": "User created",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "type": {
                "type": "string",
                "enum": [
                  "user"
                ]
              },
              "attributes": {
                "$ref": "#/components/schemas/User"
              }
            }
          }
        }
      },
      "examples": {
        "created_user": {
          "summary": "Successful user creation response",
          "value": {
            "data": {
              "id": 999,
              "type": "user",
              "attributes": {
                "email": "[email protected]",
                "name": "New User",
                "given_name": "New",
                "family_name": "User",
                "admin": false,
                "publisher_id": 123,
                "agency_id": null,
                "network_id": null,
                "referred_by_id": 55
              }
            }
          }
        }
      }
    }
  }
}

{
  "$ref": "#/components/responses/BadRequest"
}

{
  "$ref": "#/components/responses/Unauthorized"
}

{
  "$ref": "#/components/responses/Forbidden"
}

{
  "description": "Validation errors",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

API Playground

The in-page tester only supports GET. For POST, use the sample curl below or the dedicated resource docs (e.g. Contacts, Link Builder). Sign in to enable live testing with your API key.

Example request (replace YOUR_API_KEY or sign in above):

curl -X POST "https://app.hienergy.ai/api/v1/users" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
  -H "Content-Type: application/json" \
  -d '{}'