Skip to content

Users API

The Users API allows you to manage users and their addresses within an organization.

List Users

This endpoint retrieves a list of all users within a specific organization.

  • Endpoint: GET /api/o/{org}/u/
  • Authentication: ApiKeyAuthentication
  • Permissions: user:read

URL Parameters

  • org (string, required): The slug of the organization.

Response

  • 200 OK: The request was successful. The response body will contain a list of user objects. 
    [
    {
        "id": 1,
        "email": "user1@example.com",
        "username": "user1",
        "first_name": "User",
        "last_name": "One",
        "locked": false
    },
    ...
]
  • 401 UNAUTHORIZED: The API key is invalid or missing.
  • 403 FORBIDDEN: The API key does not have the required user:read permission.
  • 404 NOT FOUND: The specified organization does not exist.

Create a User

This endpoint creates a new user within a specific organization.

  • Endpoint: POST /api/o/{org}/u/
  • Authentication: ApiKeyAuthentication
  • Permissions: user:write

URL Parameters

  • org (string, required): The slug of the organization.

Request Body

  • email (string, required): The email address of the new user.
  • first_name (string, optional): The first name of the new user.
  • last_name (string, optional): The last name of the new user.

  • custom_fields (object, optional): A JSON object with custom fields.

    {
    "email": "new.user@example.com",
    "first_name": "New",
    "last_name": "User"
}

Response

  • 201 CREATED: The user was created successfully. The response body will contain the details of the new user. 
    {
    "id": 2,
    "email": "new.user@example.com",
    "username": "new.user@example.com",
    "first_name": "New",
    "last_name": "User",
    "custom_fields": {}
}
  • 400 BAD REQUEST: The request was invalid (e.g., the user already exists).
  • 401 UNAUTHORIZED: The API key is invalid or missing.
  • 403 FORBIDDEN: The API key does not have the required user:write permission.
  • 404 NOT FOUND: The specified organization does not exist.

Retrieve a User

This endpoint retrieves the details of a specific user.

  • Endpoint: GET /api/o/{org}/u/{username}/
  • Authentication: ApiKeyAuthentication
  • Permissions: user:read

URL Parameters

  • org (string, required): The slug of the organization.
  • username (string, required): The username of the user to retrieve.

Response

  • 200 OK: The request was successful. The response body will contain the user details. 
    {
    "id": 1,
    "email": "user1@example.com",
    "username": "user1",
    "first_name": "User",
    "last_name": "One",
    "locked": false
}
  • 401 UNAUTHORIZED: The API key is invalid or missing.
  • 403 FORBIDDEN: The API key does not have the required user:read permission.
  • 404 NOT FOUND: The specified organization or user does not exist.

Update a User

This endpoint updates the details of a specific user.

  • Endpoint: PUT /api/o/{org}/u/{username}/ or PATCH /api/o/{org}/u/{username}/
  • Authentication: ApiKeyAuthentication
  • Permissions: user:write

URL Parameters

  • org (string, required): The slug of the organization.
  • username (string, required): The username of the user to update.

Request Body

  • first_name (string, optional): The users first name.
  • last_name (string, optional): The users last name.
  • locked (boolean, optional): Whether the user is locked or not.
  • custom_fields (object, optional): A JSON object with custom fields.

  • _mode (string, optional): The update mode for the custom_fields. Can be REPLACE, MERGE, or IGNORE. Defaults to IGNORE.

    {
    "first_name": "Updated",
    "custom_fields": {
        "new_field": "new_value"
    },
    "_mode": "MERGE"
}

Response

  • 200 OK: The user was updated successfully.
  • 400 BAD REQUEST: The request was invalid.
  • 401 UNAUTHORIZED: The API key is invalid or missing.
  • 403 FORBIDDEN: The API key does not have the required user:write permission.
  • 404 NOT FOUND: The specified organization or user does not exist.

List User Addresses

This endpoint retrieves a list of all addresses for a specific user.

  • Endpoint: GET /api/o/{org}/u/{username}/address/
  • Authentication: ApiKeyAuthentication
  • Permissions: user:read

URL Parameters

  • org (string, required): The slug of the organization.
  • username (string, required): The username of the user.

Response

  • 200 OK: The request was successful. The response body will contain a list of address objects. 
    [
    {
        "name": "email",
        "value": "user1@example.com"
    },
    ...
]
  • 401 UNAUTHORIZED: The API key is invalid or missing.
  • 403 FORBIDDEN: The API key does not have the required user:read permission.
  • 404 NOT FOUND: The specified organization or user does not exist.

Add an Address to a User

This endpoint adds a new address to a specific user.

  • Endpoint: POST /api/o/{org}/u/{username}/address/
  • Authentication: ApiKeyAuthentication
  • Permissions: user:write

URL Parameters

  • org (string, required): The slug of the organization.
  • username (string, required): The username of the user.

Request Body

  • name (string, required): The name of the address (e.g., "email", "phone").

  • value (string, required): The value of the address.

    {
    "name": "phone",
    "value": "+1234567890"
}

Response

  • 200 OK: The address was added successfully.
  • 400 BAD REQUEST: The request was invalid.
  • 401 UNAUTHORIZED: The API key is invalid or missing.
  • 403 FORBIDDEN: The API key does not have the required user:write permission.
  • 404 NOT FOUND: The specified organization or user does not exist.