Skip to main content

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​

HeaderRequiredDescription
AuthorizationYesBearer token for a System API client
Content-TypeYesMust 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​

FieldTypeRequiredDescription
firstNamestringYesUser first name. Maximum length: 50.
lastNamestringYesUser last name. Maximum length: 50.
emailstringYesUser email address. Must be a valid email address.
sendInvitebooleanNoWhen true, the API creates the user as invited and sends an invitation email. Default: false.
triggerWebhookbooleanNoWhen true, the API sends the UserCreated webhook event to subscriptions for that event. Default: false.
redirectUrlstringConditionalAbsolute URL used in the invitation link. Required when sendInvite is true.
inviterNamestringConditionalName 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​

FieldTypeDescription
userIdintegerIdentifier of the created user

Errors​

StatusWhen it happens
400 Bad RequestThe request is invalid or the invitation flow cannot be completed
401 UnauthorizedThe bearer token is missing, invalid, or expired
403 ForbiddenThe token is valid but does not have access to this endpoint
409 ConflictA 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, Guardhouse sends the UserCreated webhook event to subscriptions for that event
  • When an invited user accepts the invitation, Guardhouse sends the UserActivated webhook event to subscriptions for that event

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 (raw HTTP)​

# The Python beta does not expose System API helpers.
# 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​