OrganizationService

Manages organizations (tenants) — creation, settings, sandbox organizations with automatic expiry, org-level privacy controls, analytics privacy parameters, and SSO attribute mappings. Users can belong to multiple organizations; the active organization is resolved per request.

Methods

Method	Description
CreateOrganization	Create a new organization
GetOrganization	Get the current organization
UpdateOrganization	Update organization settings
UpdateSsoAttributeMappings	Configure SSO attribute mappings
RotateAnalyticsSalt	Rotate the analytics salt (k-anonymization)
UpdateAnalyticsEpsilon	Update the differential privacy epsilon
GetOrgPrivacySettings	Get org-level data-processing toggles
UpdateOrgPrivacySettings	Update org-level data-processing toggles
CreateSandboxOrganization	Create a sandbox organization with an expiry
DeleteSandboxOrganization	Delete a sandbox organization
ListSandboxFixtures	List bootstrap fixtures for seeding new organizations
ListUserOrganizations	List all organizations the caller belongs to
ListUserSandboxes	List the caller’s sandbox organizations

CreateOrganization

Create a new organization. The authenticated caller becomes the initial admin; additional admins are added via invite links after the organization exists.

Authorization: Authenticated user (no specific permission required)

Request: CreateOrganizationRequest

Field	Type	Description
name	string	Organization name. Max 200 characters.
industry	Industry	Industry vertical.
company_size	CompanySize	Employee headcount range.
access_code	string	Access code required during early access. Format: PIDGR-XXXXXXXX.
data_governance_region	string	Data governance framework (EU, LATAM, BR, APAC, US). Defaults to US.
fixture_id	string	Optional bootstrap fixture to seed the organization with starter data. Empty means the default fixture.

Response: CreateOrganizationResponse

Field	Type	Description
organization	Organization	The created organization.
admin_user	User	The admin user created for the organization.

GetOrganization

Get the authenticated user’s organization.

Authorization: Requires PERMISSION_ORG_READ permission

Request: GetOrganizationRequest

Empty request. The organization is derived from the authenticated request context.

Response: GetOrganizationResponse

Field	Type	Description
organization	Organization	The organization.

UpdateOrganization

Update organization settings. Empty / unspecified fields are left unchanged.

Authorization: Requires PERMISSION_ORG_WRITE permission

Request: UpdateOrganizationRequest

Field	Type	Description
name	string	New name. Empty leaves unchanged. Max 200 characters.
default_workflow	WorkflowDefinition	New default workflow. Null leaves unchanged.
industry	Industry	New industry vertical. UNSPECIFIED leaves unchanged.
company_size	CompanySize	New headcount range. UNSPECIFIED leaves unchanged.
default_locale	string	New default language for new users (en, es, pt-BR, zh, ja). Empty leaves unchanged.
ml_retrain_cold_threshold	int32	New ML cold-start threshold. 0 leaves unchanged; otherwise must be in [1, 100].
ml_cancelled_counts	optional bool	Whether cancelled campaigns count toward the training counter. Unset leaves unchanged.
ml_manual_limit_monthly	int32	New monthly manual retrain limit. -1 leaves unchanged; otherwise must be in [0, 10].
include_synthetic_in_aggregates	optional bool	Whether aggregate stats include synthetic data. Unset leaves unchanged.
provisional_archetypes_enabled	optional bool	Opt-in to provisional archetypes for standard organizations. Unset leaves unchanged; rejected for sandbox organizations.

Response: UpdateOrganizationResponse

Field	Type	Description
organization	Organization	The updated organization.

UpdateSsoAttributeMappings

Replace all SSO attribute mappings for the organization. Mappings define how identity provider claims populate Pidgr user profile fields when users authenticate via SSO.

Authorization: Requires PERMISSION_ORG_WRITE permission

Request: UpdateSsoAttributeMappingsRequest

Field	Type	Description
sso_attribute_mappings	SsoAttributeMapping[]	Complete list of mappings (replaces all existing mappings).

Response: UpdateSsoAttributeMappingsResponse

Field	Type	Description
organization	Organization	The updated organization with the new SSO mappings.

RotateAnalyticsSalt

Rotate the analytics salt and optionally increase the bucket count used for k-anonymization.

Authorization: Requires PERMISSION_PRIVACY_WRITE permission

Request: RotateAnalyticsSaltRequest

Field	Type	Description
new_bucket_count	int32	New bucket count. Must be >= current. 0 keeps the current count.

Response: RotateAnalyticsSaltResponse

Field	Type	Description
bucket_count	int32	The bucket count after rotation.

UpdateAnalyticsEpsilon

Update the differential privacy epsilon parameter for analytics.

Authorization: Requires PERMISSION_PRIVACY_WRITE permission

Request: UpdateAnalyticsEpsilonRequest

Field	Type	Description
epsilon	float	New epsilon value. Range [0.5, 5.0].

Response: UpdateAnalyticsEpsilonResponse

Field	Type	Description
epsilon	float	The new epsilon value.

GetOrgPrivacySettings

Retrieve org-level data-processing toggles (AI clustering, behavioral analytics, third-party channels), each with last-changed-by/at metadata for a verifiable consent trail.

Authorization: Requires PERMISSION_PRIVACY_READ permission

Request: GetOrgPrivacySettingsRequest

Empty request.

Response: GetOrgPrivacySettingsResponse

Field	Type	Description
settings	OrgPrivacySettings	The organization’s current privacy settings.

UpdateOrgPrivacySettings

Update org-level data-processing toggles. Only the provided fields change; each change is recorded with the acting admin and timestamp.

Authorization: Requires PERMISSION_PRIVACY_WRITE permission

Request: UpdateOrgPrivacySettingsRequest

Field	Type	Description
ai_clustering_enabled	optional bool	Enable/disable ML archetype clustering and ACK predictions. Unset leaves unchanged.
behavioral_analytics_enabled	optional bool	Enable/disable behavioral analytics (session replay, heatmaps). Unset leaves unchanged.
third_party_channels_enabled	optional bool	Enable/disable third-party notification channels. Unset leaves unchanged.

Response: UpdateOrgPrivacySettingsResponse

Field	Type	Description
settings	OrgPrivacySettings	The privacy settings after the update.

CreateSandboxOrganization

Create a sandbox organization for testing configurations. Sandbox organizations auto-delete after expires_at; the caller becomes super admin.

Authorization: Any authenticated user. Limited to 3 concurrent sandboxes per user.

Request: CreateSandboxOrganizationRequest

Field	Type	Description
name	string	Sandbox name. Max 200 characters.
expires_at	Timestamp	Required expiration time. Max 30 days from now for interactive callers; API-key callers may set shorter TTLs.
data_governance_region	string	Data governance framework (EU, LATAM, BR, APAC, US). Defaults to US.
fixture_id	string	Optional bootstrap fixture. Must match an id returned by ListSandboxFixtures. Empty means the default fixture.

Response: CreateSandboxOrganizationResponse

Field	Type	Description
organization	Organization	The created sandbox organization (org_type: SANDBOX).
admin_user	User	The admin user created for the sandbox.

DeleteSandboxOrganization

Delete a sandbox organization immediately. Deletion runs asynchronously — a success response means the cleanup workflow started. Only callable for organizations with org_type SANDBOX.

Authorization: Super admin of the target sandbox or its creator

Request: DeleteSandboxOrganizationRequest

Field	Type	Description
org_id	string	ID of the sandbox organization to delete.

Response: DeleteSandboxOrganizationResponse

Field	Type	Description
workflow_id	string	ID of the workflow handling the deletion.

ListSandboxFixtures

List bootstrap fixtures available for seeding new organizations. The catalog is the same for all callers.

Authorization: Any authenticated user

Request: ListSandboxFixturesRequest

Empty request.

Response: ListSandboxFixturesResponse

Field	Type	Description
fixtures	SandboxFixture[]	All registered fixtures, ordered by name.

SandboxFixture

Field	Type	Description
id	string	Stable slug (e.g. starter, empty). Pass back as fixture_id on create.
name	string	Display name.
description	string	Description shown alongside the fixture option.
is_default	bool	Exactly one fixture has is_default=true.

ListUserOrganizations

List all organizations the authenticated user belongs to. Callable without an active organization context — used by clients to discover available organizations. Excludes expired sandbox organizations.

Authorization: Authenticated user (no specific permission required)

Request: ListUserOrganizationsRequest

Empty request.

Response: ListUserOrganizationsResponse

Field	Type	Description
organizations	Organization[]	Organizations the user belongs to, ordered by creation time.

ListUserSandboxes

List only the sandbox organizations the authenticated user belongs to. Callable without an active organization context. Excludes already-expired sandboxes.

Authorization: Authenticated user (no specific permission required)

Request: ListUserSandboxesRequest

Empty request.

Response: ListUserSandboxesResponse

Field	Type	Description
sandboxes	Organization[]	Sandbox organizations, ordered by expires_at ascending (soonest-expiring first).

Organization Message

Field	Type	Description
id	string	Unique identifier.
name	string	Organization name. Max 200 characters.
default_workflow	WorkflowDefinition	Default workflow used when campaigns don’t specify one.
created_at	Timestamp	Creation timestamp.
industry	Industry	Industry vertical.
company_size	CompanySize	Employee headcount range.
sso_attribute_mappings	SsoAttributeMapping[]	SSO claim-to-profile mappings. Empty when SSO is not used.
default_locale	string	Default language for new users (en, es, pt-BR, zh, ja). Empty means auto-detect.
org_type	OrgType	Organization lifecycle type.
expires_at	Timestamp	Expiration time for sandbox organizations. Empty for standard organizations.
data_governance_region	string	Data governance framework (EU, LATAM, BR, APAC, US).
data_content_region	string	Region where content is stored, resolved from data_governance_region.
ml_retrain_cold_threshold	int32	Cold-start threshold for ML retraining. Default 10, range 1–100.
ml_cancelled_counts	bool	Whether cancelled campaigns count toward the training counter. Default true.
ml_manual_limit_monthly	int32	Monthly limit on manual retrain triggers. Default 3, range 0–10.
ml_manual_retrains_used	int32	Manual retrains used in the current month.
ml_needs_retrain	bool	Whether the org is flagged for the next scheduled training run.
campaigns_since_last_training	int32	Campaigns completed since the last ML training run.
total_completed_campaigns	int32	Total campaigns completed across the organization lifetime.
last_ml_training_at	Timestamp	Most recent successful ML training. Empty if never trained.
include_synthetic_in_aggregates	optional bool	Whether aggregate stats include synthetic data. Unset defaults by org type (sandbox: include, standard: exclude).
provisional_archetypes_enabled	bool	Opt-in to provisional archetypes for standard organizations. Sandbox organizations are always eligible.

SsoAttributeMapping

Field	Type	Description
idp_claim	string	Claim name from the identity provider (e.g. given_name). Max 500 characters.
profile_field	string	Target UserProfile field name (e.g. department). For custom attributes, use the custom: prefix (e.g. custom:cost_center). Max 100 characters.

Enums

Industry

TECHNOLOGY, FINANCE, HEALTHCARE, EDUCATION, RETAIL, MANUFACTURING, MEDIA, OTHER

CompanySize

COMPANY_SIZE_1_200 (1–200), COMPANY_SIZE_200_500 (200–500), COMPANY_SIZE_500_1000 (500–1000), COMPANY_SIZE_1000_5000 (1000–5000), COMPANY_SIZE_5000_PLUS (5000+)

OrgType

Value	Description
ORG_TYPE_STANDARD	Standard organization
ORG_TYPE_SANDBOX	Sandbox organization with an expiry (expires_at)
ORG_TYPE_STAFF	Reserved for platform operations; cannot be created via CreateOrganization