Partner Users

Partner users represent individual customer accounts within a partner's white-label solution. Each partner user functions as a completely isolated sub-account with its own resources, including bots, datasets, conversations, integrations, and settings. This isolation enables partners to build multi-tenant SaaS solutions on top of the ChatBotKit platform without customers being aware of the underlying infrastructure.

Creating Partner Users

To create a new partner user (sub-account), you need to send a POST request to the partner user creation endpoint. This operation can only be performed by the parent partner account, and the created user will be linked to your partner account, inheriting billing and subscription settings while maintaining operational independence.

When creating a partner user, you can configure various properties including the user's display name, description, profile image, contact email, and resource limits. The contact email is particularly important as it allows you to associate customer contact information with the sub-account for communication and support purposes.

The API returns the ID of the newly created partner user, which you'll use for all subsequent operations related to this sub-account. Store this ID securely as it's required for managing the partner user's resources and performing operations on their behalf using the X-RunAs-UserId header.

Important: Partner users share billing and subscription limits with the parent partner account. Ensure your partner account has sufficient capacity to accommodate all sub-accounts and their resource usage. Resource limits can be customized per partner user to control their individual usage caps.

Deleting Partner Users

To permanently remove a partner user (sub-account) and all associated resources, send a POST request to the partner user delete endpoint. This operation is irreversible and will completely delete the partner user's account along with all their bots, datasets, conversations, integrations, files, and other resources.

Deleting a partner user should be done with extreme caution as it represents a complete account termination. All data belonging to the partner user will be permanently removed from the system, and there is no recovery mechanism. This operation is typically used when a customer cancels their subscription or when you need to clean up test or inactive accounts.

Before deleting a partner user, consider whether you need to export or archive any of their data. Once deletion is complete, all conversation histories, trained models, uploaded files, and custom configurations are permanently removed and cannot be recovered.

Critical Warning: This operation cascades through all related resources. When a partner user is deleted, the system automatically removes all their bots, datasets, conversations, messages, integrations, API tokens, files, and any other resources they own. Ensure you have explicit confirmation from the customer before proceeding with account deletion.

Compliance: If you're subject to data retention regulations (such as GDPR, CCPA, or industry-specific requirements), ensure you have appropriate data export and archival processes in place before deleting partner user accounts. Some regulations require maintaining certain records even after account closure.

Best Practice: Implement a soft-delete or account suspension feature in your application layer before permanently deleting partner users. This provides a grace period where accounts can be restored if deletion was requested in error or if customers change their minds.

Fetching Partner User Details

To retrieve detailed information about a specific partner user (sub-account), send a GET request to the partner user fetch endpoint with the user's ID. This operation returns comprehensive information about the sub-account, including all configuration settings, limits, and metadata.

Fetching individual partner user details is useful when you need to display account information, verify configuration settings, or prepare data for update operations. The endpoint provides a complete snapshot of the partner user's current state without including sensitive authentication credentials.

The response includes the partner user's ID, name, description, profile image, contact email, resource limits, custom metadata, and timestamp information. This data can be used to populate forms for editing, display account dashboards, or validate partner user configurations.

Use Case: When building a partner dashboard, use this endpoint to load detailed information for a specific customer account when a user clicks on it from the list view. This allows you to show comprehensive account details and provide edit functionality without loading all data upfront.

Updating Partner Users

You can modify a partner user's (sub-account's) properties by sending a POST request to the partner user update endpoint. This operation allows you to change the user's name, description, profile image, contact email, resource limits, and custom metadata without affecting their underlying resources or authentication credentials.

Updates to partner users are particularly useful when customer information changes, you need to adjust resource allocations, or you want to update branding elements like profile images. All properties except the user's ID and internal authentication details can be modified through this endpoint.

The update operation is atomic and validates all input parameters before applying any changes. If validation fails, no modifications are made to the partner user account. The API returns the updated user's ID upon successful completion, confirming that changes have been applied.

Important: Updating resource limits affects what the partner user can create and access within their sub-account. Be cautious when reducing limits, as it may prevent the partner user from creating new resources until they're within the new constraints. Existing resources are not automatically deleted when limits are reduced.

Best Practice: When implementing an admin interface for managing partner users, fetch the current settings first, allow editing, then submit only the changed fields along with unchanged required fields to maintain consistency.

Listing Partner Users

You can retrieve a list of all partner users (sub-accounts) associated with your partner account by sending a GET request to the partner user list endpoint. This operation returns paginated results, allowing you to efficiently manage large numbers of customer accounts.

The list endpoint supports pagination through cursor-based navigation, enabling you to retrieve results in manageable chunks. You can control the order of results (ascending or descending by creation date) and specify how many items to retrieve per request using query parameters.

Each partner user in the response includes their basic information such as ID, name, profile image, contact email, configured limits, metadata, and timestamps for when the account was created and last updated. This information allows you to build comprehensive dashboards and management interfaces for your partner solution.

The response also includes pagination metadata when applicable, providing cursors for fetching the next page of results. This is particularly useful when building user interfaces that need to display large lists of customer accounts with smooth scrolling or pagination controls.

Best Practice: Implement caching strategies for partner user lists when building dashboards or management interfaces. Consider storing frequently accessed partner user data locally and refreshing it periodically or when updates occur, rather than fetching the entire list on every page load.

Note: The list endpoint only returns partner users that belong to your parent partner account. You cannot access partner users from other partner accounts, ensuring complete isolation between different partner solutions.