---
title: "Create Society From Integrations"
method: POST
path: "/v1/societies/create-from-integrations"
tags: ["societies"]
---

# Create Society From Integrations

`POST /v1/societies/create-from-integrations`

## Request

- Base URL: `https://api.evidenso.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.evidenso.com/v1/societies/create-from-integrations`
- Auth: HTTP bearer

Kick off a society-creation orchestration. The actual ingest +
pipeline run happens asynchronously; the response returns the
society_id immediately so the UI can show in-progress state.

Mode 2 prerequisite: every selected integration must already have
an active OAuth connection for the requesting user (set up through
Settings → Integrations). The orchestrator surfaces missing
connections as `last_error` on the corresponding row in
`society_source_connections`.

## Request body

- SocietyCreationRequest: Mirrors the AddSocietyModal `PrototypeSociety` payload shape (see `evidenso-ui/client/src/components/AddSocietyModal.tsx`).
  - `market` string, required: Market slug, e.g. 'b2b_saas'.
  - `displayName` string, required
  - `description` string
  - `sourceMode` 'market' | 'customer' | 'mixed' | 'agent_documents': 'customer' fetches from the user's Composio integrations; 'agent_documents' ingests documents the user's agent already extracted and stashed via the MCP tool (no Composio fetch — requires agent_payload_id). Downstream the pipeline treats agent_documents identically to customer.
  - `agentPayloadId` string: Id of a row in mcp_agent_document_payloads holding the agent-supplied documents. Required when source_mode='agent_documents'; ignored otherwise.
  - `selectedMarketSignals` string[]
  - `selectedIntegrations` string[]: Composio toolkit slugs to fetch from (e.g. 'granola_mcp'). Empty list when source_mode='market'.
  - `scopeByIntegration` object: Per-source scope keyed by wireSlug (matches selected_integrations). Persisted into society_source_connections.scope_config and honored by the bronze_integrations_snapshot fetch step. Slack: {mode, channel_ids}. Google: {mode, folder_ids, file_ids}. Granola: {mode, meeting_ids, folder_ids}. HubSpot: {mode: selected, contact_ids}, 1–50 contacts. Empty dict = full-access default except HubSpot, which requires selection.
  - `requirements` string
  - `productName` string
  - `populationRows` integer
  - `marketReportCount` integer
  - `toolResearchCount` integer
  - `mindsetClusterCount` integer
  - `extendedDocCount` integer
  - `socialPerSourceN` integer, nullable
  - `llmStack` 'openai' | 'google', nullable: Model family preset. When omitted, Mode 1 defaults to 'openai' and Mode 2/mixed defaults to 'google' inside the orchestrator (preserves pre-feature behavior).

## Response `200`

Successful Response

- SocietyCreationResponse
  - `society_id` string, required: Society UUID (matches personas.society_id and /v1/personas/groups). Use this for in-progress card → real society reconciliation in the UI.
  - `society_key` string, required: Composite 'market/name' identifier used by digital-twin-api Gold tables. Useful for cross-service URLs.
  - `market` string, required
  - `name` string, required
  - `job_id` string, nullable: Pre-allocated pipeline job_id. Present from the moment this endpoint returns (no more polling /v1/societies/pipeline-job to dereference (market, name) → job_id). The UI uses this to wire the in-progress card to /pipelines/jobs/{id} immediately. May be null only if pre-allocation failed — in which case the UI falls back to the legacy dereference path until the orchestrator stashes a job_id on the society_source_connections rows.
  - `eta` object, nullable: Expected pipeline runtime in minutes — from digital-twin-api's ``pipeline_eta`` helper at preallocation time. Shape: ``{expected_minutes, p90_minutes, basis, step_share}``. The MCP tool renders this so the agent can tell the user the expected duration upfront. May be omitted when pre-allocation couldn't return an estimate (rare; pipeline still runs).

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/evidenso/apis/persona-rag-api.md) - [All operations](https://skmtc.dev/evidenso/apis/persona-rag-api/llms.txt) - [OpenAPI document](https://skmtc.dev/evidenso/apis/persona-rag-api/revisions/86408c178d4f?raw)