> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convocore.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Organization
> Create a new organization under the authenticated workspace
Creates an organization (the “client” card in the dashboard Clients page). Returns `orgId` plus the full org document in `data`.
## Example Request
Minimal:
```json theme={null}
{
"name": "Acme Corp",
"email": "ops@acme.example",
"squarePhotoURL": "https://example.com/logo.png"
}
```
With optional org fields (agents, access tabs, language, settings):
```json theme={null}
{
"name": "Acme Corp",
"email": "ops@acme.example",
"squarePhotoURL": "https://example.com/logo.png",
"preferredLanguage": "en",
"widgetIDs": ["agent_abc123"],
"canAccess": ["/home", "/convos", "/leads"],
"settings": {
"disableClientAccess": false
}
}
```
Server sets ownership fields (`ID`, `userId`, `agencyId`, `ts`, `type: "org"`). Use `PATCH /orgs/{orgId}` to change more fields later.
After creating an org, assign agents with `POST /orgs/{orgId}/agents/{agentId}` and add users with `POST /clients`. Fetch the full document anytime with `GET /orgs/{orgId}`.
## OpenAPI
````yaml POST /orgs
openapi: 3.0.3
info:
title: Convocore OpenAPI
description: Full API reference for Convocore
version: 1.0.4
servers:
- url: https://eu-gcp-api.vg-stuff.com/v3
security: []
paths:
/orgs:
post:
tags:
- Organizations
summary: Create Organization
description: >-
Creates a new organization (client workspace) under the authenticated
agency workspace
operationId: orgsRouter-createOrg
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 1
description: Display name for the organization (Clients page card).
email:
type: string
description: >-
The email of the client which will be used by them to sign
in also can be used in your whitelabel dashboard to autofill
by appending ?email=test@gmail.
squarePhotoURL:
type: string
description: Photo URL of the client, will show on their dashboard.
widgets:
type: array
description: The widgets of the client (USED BY SYTEM ONLY)
items: {}
widgetIDs:
$ref: '#/components/schemas/array_93f0da0d'
dashboardUsername:
type: string
description: The username of the dashboard (DEPRACATED NOT USED)
dashboardPassword:
type: string
description: >-
The sign in dashboard for the client, used along the email
to sign in to the whitelabel dashboard append ?password=123
to autofill the fields on the dashboard login.
canAccess:
$ref: '#/components/schemas/array_ec9e236b'
allowedChannels:
$ref: '#/components/schemas/array_fce2e4dd'
allowedIntegrations:
$ref: '#/components/schemas/array_26d79638'
clientTabOrder:
$ref: '#/components/schemas/array_a1466f1c'
magicCode:
type: string
description: >-
The magic code of the client, used to sign in to the
dashboard.
index:
type: number
description: The index of the client, used to sort the clients.
isAdmin:
type: boolean
description: >-
Whether the client is an org admin or not allowing him to
create other users on his org and have more access in the
dashboard.
usedSecret:
type: string
description: The secret of the client, used to sign in to the dashboard.
orgId:
type: string
description: >-
The ID of the org this user belongs to, must be defined when
creating a client.
isOrgAdmin:
type: boolean
description: >-
Whether the client is an organization admin or not allowing
him to create other users on his org and have more access in
the dashboard
canDelegateChats:
type: boolean
description: >-
Whether the client can delegate chats to other users in the
org.
status:
$ref: '#/components/schemas/string_22b2602f'
predefinedTags:
$ref: '#/components/schemas/array_5522c2ea'
FB_PUSH_TOKEN:
type: string
description: >-
The Firebase push token of the client used to implement
browser notifications.
notificationsSettings:
$ref: >-
#/components/schemas/notifyThrough_notifyIf_emailNotifyOnNewLead_01e143
handoff:
$ref: '#/components/schemas/maxAssignees_18f727'
lastEmailSentTS:
type: number
description: >-
The timestamp of the last email sent, used by the system to
not send a lot of emails to the client.
preferredLanguage:
type: string
description: >-
The preferred language of the client and based on it whole
whitelabel dashboard will be translated, MUST BE 2 letter
language code
internal:
$ref: '#/components/schemas/hasChangedPassword_3d803f'
lastInvitationTs:
type: number
description: The timestamp of the last invitation
cannedResponses:
$ref: '#/components/schemas/array_ac402328'
stripeCustomerId:
type: string
description: The Stripe customer ID of the client
signupSource:
type: string
description: Signup source for client onboarding (e.g. stripe_checkout)
allowCreateAgents:
type: boolean
description: Whether the client can create agents
hideAdvancedSettings:
type: boolean
description: Whether the client can hide the advanced settings
onboardingState:
$ref: >-
#/components/schemas/currentStep_isCompleted_completedSteps_personalInfo_cc96c0
isNewSignup:
type: boolean
description: >-
Flag to identify clients created through signup (triggers
onboarding)
teams:
$ref: '#/components/schemas/array_883352cb'
adminIDs:
type: array
items:
type: string
supportIDs:
type: array
items:
type: string
canSelfEdit:
type: boolean
lastModified:
type: number
defaultClientAccess:
type: array
items:
type: string
defaultClientTabOrder:
type: array
items:
type: string
convoTags:
type: array
items:
type: string
enableHumanHandoff:
type: boolean
dashboardLayout:
type: string
enum:
- vertical
- horizontal
settings:
$ref: '#/components/schemas/disableClientAccess_5b1d9c'
required:
- name
additionalProperties: true
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
orgId:
type: string
description: Created organization id (same as data.ID).
data:
type: object
properties:
ID:
type: string
description: The ID of the client
firebaseUid:
type: string
description: The Firebase UID of the client
agencyId:
type: string
description: The ID of the agency
userId:
type: string
description: The ID of the user
ownerID:
type: string
description: The owner ID of the workspace that owns this client.
name:
type: string
description: The name of the client
email:
type: string
description: >-
The email of the client which will be used by them to
sign in also can be used in your whitelabel dashboard
to autofill by appending ?email=test@gmail.
squarePhotoURL:
type: string
description: Photo URL of the client, will show on their dashboard.
widgets:
type: array
description: The widgets of the client (USED BY SYTEM ONLY)
items: {}
widgetIDs:
$ref: '#/components/schemas/array_93f0da0d'
dashboardUsername:
type: string
description: The username of the dashboard (DEPRACATED NOT USED)
dashboardPassword:
type: string
description: >-
The sign in dashboard for the client, used along the
email to sign in to the whitelabel dashboard append
?password=123 to autofill the fields on the dashboard
login.
ts:
type: number
description: UNIX timestamb of the last change done on the client.
canAccess:
$ref: '#/components/schemas/array_ec9e236b'
allowedChannels:
$ref: '#/components/schemas/array_fce2e4dd'
allowedIntegrations:
$ref: '#/components/schemas/array_26d79638'
clientTabOrder:
$ref: '#/components/schemas/array_a1466f1c'
magicCode:
type: string
description: >-
The magic code of the client, used to sign in to the
dashboard.
index:
type: number
description: The index of the client, used to sort the clients.
isAdmin:
type: boolean
description: >-
Whether the client is an org admin or not allowing him
to create other users on his org and have more access
in the dashboard.
usedSecret:
type: string
description: >-
The secret of the client, used to sign in to the
dashboard.
orgId:
type: string
description: >-
The ID of the org this user belongs to, must be
defined when creating a client.
type:
type: string
enum:
- client
- org
isOrgAdmin:
type: boolean
description: >-
Whether the client is an organization admin or not
allowing him to create other users on his org and have
more access in the dashboard
canDelegateChats:
type: boolean
description: >-
Whether the client can delegate chats to other users
in the org.
status:
$ref: '#/components/schemas/string_22b2602f'
predefinedTags:
$ref: '#/components/schemas/array_5522c2ea'
FB_PUSH_TOKEN:
type: string
description: >-
The Firebase push token of the client used to
implement browser notifications.
notificationsSettings:
$ref: >-
#/components/schemas/notifyThrough_notifyIf_emailNotifyOnNewLead_01e143
handoff:
$ref: '#/components/schemas/maxAssignees_18f727'
lastEmailSentTS:
type: number
description: >-
The timestamp of the last email sent, used by the
system to not send a lot of emails to the client.
preferredLanguage:
type: string
description: >-
The preferred language of the client and based on it
whole whitelabel dashboard will be translated, MUST BE
2 letter language code
internal:
$ref: '#/components/schemas/hasChangedPassword_3d803f'
lastInvitationTs:
type: number
description: The timestamp of the last invitation
cannedResponses:
$ref: '#/components/schemas/array_ac402328'
stripeCustomerId:
type: string
description: The Stripe customer ID of the client
signupSource:
type: string
description: >-
Signup source for client onboarding (e.g.
stripe_checkout)
allowCreateAgents:
type: boolean
description: Whether the client can create agents
hideAdvancedSettings:
type: boolean
description: Whether the client can hide the advanced settings
onboardingState:
$ref: >-
#/components/schemas/currentStep_isCompleted_completedSteps_personalInfo_cc96c0
isNewSignup:
type: boolean
description: >-
Flag to identify clients created through signup
(triggers onboarding)
teams:
$ref: '#/components/schemas/array_883352cb'
adminIDs:
type: array
items:
type: string
supportIDs:
type: array
items:
type: string
canSelfEdit:
type: boolean
workspaceId:
type: string
lastModified:
type: number
defaultClientAccess:
type: array
items:
type: string
defaultClientTabOrder:
type: array
items:
type: string
convoTags:
type: array
items:
type: string
enableHumanHandoff:
type: boolean
dashboardLayout:
type: string
enum:
- vertical
- horizontal
settings:
$ref: '#/components/schemas/disableClientAccess_5b1d9c'
additionalProperties: true
description: Full organization document after create.
required:
- success
- message
- orgId
- data
additionalProperties: false
default:
$ref: '#/components/responses/error'
security:
- Authorization: []
components:
schemas:
array_93f0da0d:
type: array
items:
type: string
description: The IDs of agents assigned to this client.
array_ec9e236b:
type: array
items:
type: string
description: >-
The tabs hrefs the user can access, example ['/home', '/convos',
'/leads', '/kb', '/analytics', '/theme', '/settings', '/prompt']
array_fce2e4dd:
type: array
items:
type: string
description: >-
Channels this client can use on the channels page. Use ["all"] or omit
for every channel.
array_26d79638:
type: array
items:
type: string
description: >-
Integrations this client can use on the integrations page. Use ["all"]
or omit for every integration.
array_a1466f1c:
type: array
items:
type: string
description: >-
The order of the client tabs, example ['home', 'convos', 'leads', 'kb',
'analytics', 'theme', 'settings', 'prompt']
string_22b2602f:
type: string
enum:
- online
- offline
description: >-
Shows on the dashboard and in the web widget whether this client is
online of offline for realtime handoff.
array_5522c2ea:
type: array
items:
type: string
description: >-
Predefined tags for the client, used in the chats tab quickly tag any
chat with them.
notifyThrough_notifyIf_emailNotifyOnNewLead_01e143:
type: object
properties:
notifyThrough:
$ref: '#/components/schemas/string_de19b267'
notifyIf:
$ref: '#/components/schemas/string_846e7443'
emailNotifyOnNewLead:
type: boolean
description: >-
Whether the client wants to receive email notifications on capturing
any new leads from calls.
required:
- notifyThrough
- notifyIf
additionalProperties: false
description: >-
The notifications settings of the client, by default the client will
only receive email notifications for requests.
maxAssignees_18f727:
type: object
properties:
maxAssignees:
type: number
description: The maximum number of assignees for handoff
additionalProperties: false
hasChangedPassword_3d803f:
type: object
properties:
hasChangedPassword:
type: boolean
description: Whether the client has changed the password
additionalProperties: false
description: Used internally by system.
array_ac402328:
type: array
items:
$ref: '#/components/schemas/key_content_2793e5'
description: 'The canned responses of the client used in the chats tab '
currentStep_isCompleted_completedSteps_personalInfo_cc96c0:
type: object
properties:
currentStep:
type: number
isCompleted:
type: boolean
completedSteps:
type: array
items:
type: number
personalInfo:
$ref: '#/components/schemas/fullName_companyName_role_industry_22cbd6'
preferences:
$ref: >-
#/components/schemas/primaryUseCase_communicationPreferences_goals_5d5593
setupData:
$ref: '#/components/schemas/selectedAgents_customizations_619638'
additionalProperties: false
description: Client onboarding state and progress
array_883352cb:
type: array
items:
$ref: '#/components/schemas/ID_key_label_description_7bb0e9'
description: >-
The teams this client belongs to (fetched from orgs/{orgId}/teams
subcollection based on memberIds)
disableClientAccess_5b1d9c:
type: object
properties:
disableClientAccess:
type: boolean
additionalProperties: true
string_de19b267:
type: string
enum:
- email
- push
- all
- none
description: The notification through
string_846e7443:
type: string
enum:
- all
- requestsOnly
- none
description: The notification if
key_content_2793e5:
type: object
properties:
key:
type: string
description: The key of the canned response
content:
type: string
description: The content of the canned response
additionalProperties: false
fullName_companyName_role_industry_22cbd6:
type: object
properties:
fullName:
type: string
companyName:
type: string
role:
type: string
industry:
type: string
additionalProperties: false
primaryUseCase_communicationPreferences_goals_5d5593:
type: object
properties:
primaryUseCase:
type: string
communicationPreferences:
type: array
items:
type: string
goals:
type: array
items:
type: string
additionalProperties: false
selectedAgents_customizations_619638:
type: object
properties:
selectedAgents:
type: array
items:
type: string
customizations: {}
additionalProperties: false
ID_key_label_description_7bb0e9:
type: object
properties:
ID:
type: string
key:
type: string
label:
type: string
description:
type: string
orgId:
type: string
additionalProperties: false
message_11569e:
type: object
properties:
message:
type: string
required:
- message
additionalProperties: false
responses:
error:
description: Error response
content:
application/json:
schema:
type: object
properties:
message:
type: string
code:
type: string
issues:
type: array
items:
$ref: '#/components/schemas/message_11569e'
required:
- message
- code
additionalProperties: false
securitySchemes:
Authorization:
type: http
scheme: bearer
````