Create User

Create a new user in Guardhouse.

Authentication

This endpoint requires a bearer access token for the System API.

Endpoint

POST /api/v1/users
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer token for a System API client
Content-Type	Yes	Must be application/json

Query Parameters

This endpoint does not accept query parameters.

Request Body

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "sendInvite": true,
  "triggerWebhook": true,
  "redirectUrl": "https://app.example.com/invitation",
  "inviterName": "Jane Admin"
}

Request Fields

Field	Type	Required	Description
firstName	string	Yes	User first name. Maximum length: 50.
lastName	string	Yes	User last name. Maximum length: 50.
email	string	Yes	User email address. Must be a valid email address.
sendInvite	boolean	No	When true, the API creates the user as invited and sends an invitation email. Default: false.
triggerWebhook	boolean	No	When true, the API triggers the user-created webhook flow. Default: false.
redirectUrl	string	Conditional	Absolute URL used in the invitation link. Required when sendInvite is true.
inviterName	string	Conditional	Name shown in the invitation email. Required when sendInvite is true. Maximum length: 150.

Validation Rules

• firstName is required and must not exceed 50 characters
• lastName is required and must not exceed 50 characters
• email must be a valid email address
• redirectUrl must be an absolute URL when provided
• inviterName must not exceed 150 characters
• When sendInvite is true, both redirectUrl and inviterName are required

Response

200 OK

Returns the identifier of the created user.

{
  "userId": 123
}

Response Fields

Field	Type	Description
userId	integer	Identifier of the created user

Errors

Status	When it happens
400 Bad Request	The request is invalid or the invitation flow cannot be completed
401 Unauthorized	The bearer token is missing, invalid, or expired
403 Forbidden	The token is valid but does not have access to this endpoint
409 Conflict	A user with the same email already exists

409 Example

User with email '[email protected]' already exists

Behavior

• The API normalizes the email address to lowercase before storing it
• When sendInvite is false, the created user starts in Staged status
• When sendInvite is true, the created user starts in Invited status and an invitation email is sent
• The user is created with emailConfirmed = false
• When triggerWebhook is true, the user-created webhook flow is triggered

Example

cURL

curl -X POST "https://your-tenant.guardhouse.cloud/api/v1/users" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "sendInvite": true,
    "triggerWebhook": true,
    "redirectUrl": "https://app.example.com/invitation",
    "inviterName": "Jane Admin"
  }'

.NET SDK

using Guardhouse.SDK.Models.Users;
using Guardhouse.SDK.Services;

// Assumes AddGuardhouseClientWithApiClients(...) is already configured.
app.MapPost("/example/users", async (IGuardhouseUsersClient usersClient) =>
{
    var createdUser = await usersClient.CreateUserAsync(new CreateUserRequest
    {
        FirstName = "John",
        LastName = "Doe",
        Email = "[email protected]",
        SendInvite = true,
        TriggerWebhook = true,
        RedirectUrl = "https://app.example.com/invitation",
        InviterName = "Jane Admin"
    });

    return Results.Ok(createdUser);
});

Python SDK

# SDK support is in development.
# Use raw HTTP for now.
#
# Example shape:
# response = requests.post(
#     "https://your-tenant.guardhouse.cloud/api/v1/users",
#     headers={
#         "Authorization": "Bearer YOUR_ACCESS_TOKEN",
#         "Content-Type": "application/json",
#     },
#     json={
#         "firstName": "John",
#         "lastName": "Doe",
#         "email": "[email protected]",
#         "sendInvite": True,
#         "triggerWebhook": True,
#         "redirectUrl": "https://app.example.com/invitation",
#         "inviterName": "Jane Admin",
#     },
# )

Notes

• Use Get User By ID or Get Users to retrieve the created user.
• Use Getting Access Credentials if you still need to configure a System API client or obtain a token.