> ## Documentation Index > Fetch the complete documentation index at: https://docs.talqui.chat/llms.txt > Use this file to discover all available pages before exploring further. # Onboard operator > Creates the operator of the authenticated account. Takes an access token (`Bearer tq_at_...`) of an account with a verified e-mail and no operator yet; the e-mail becomes the operator's address. Idempotent: when the account already has an operator the answer is **409** `OperatorAlreadyOnboardedError` with that operator in `data.operator`, so a retry can be treated as success. The response carries no token. Refresh the access token afterwards: the current one may keep resolving to the account without an operator for up to two minutes. ## OpenAPI ````yaml /api/services-api.yaml post /v1/operators/onboarding openapi: 3.0.3 info: description: >- Talqui is an omnichannel customer service platform that unifies conversations from WhatsApp, Instagram, Telegram, and many other channels into a single attendant panel, alongside a broader ecosystem of plugins and integrations. This API gives developers programmatic access to Talqui's services layer, exposing the operations needed to read and manage tenants, conversations, plugins, and related resources that power that platform. Authentication is available on behalf of an Operator (the default for this API), a Plugin Connection, or a Plugin — see the [Talqui authentication guide](https://docs.talqui.chat/guides/introduction/authentication/) for how each token is obtained and when to use it. Need help or have questions not covered here? Reach out to support@talqui.com. license: name: ISC url: https://opensource.org/license/isc-license-txt title: Talqui - Services API version: 0.99.0 servers: - description: Production url: https://services-api.talqui.chat security: [] tags: - name: Tenants - name: Settings - name: Analytics/Reports - name: Analytics - name: Campaigns - name: Campaigns/Models - name: Contacts - name: Contacts/Imports - name: Handoff links - name: Inboxes - name: Messages - name: Notifications - name: Sessions - name: Operators/Shortcuts - name: Operators - name: Plugins - name: Milestones - name: Invites paths: /v1/operators/onboarding: post: tags: - Operators summary: Onboard operator description: >- Creates the operator of the authenticated account. Takes an access token (`Bearer tq_at_...`) of an account with a verified e-mail and no operator yet; the e-mail becomes the operator's address. Idempotent: when the account already has an operator the answer is **409** `OperatorAlreadyOnboardedError` with that operator in `data.operator`, so a retry can be treated as success. The response carries no token. Refresh the access token afterwards: the current one may keep resolving to the account without an operator for up to two minutes. operationId: OnboardOperatorController parameters: [] requestBody: content: application/json: schema: properties: operatorFirstname: description: Given name. minLength: 1 type: string operatorLastname: description: Family name. minLength: 1 type: string operatorPhone: description: Phone number. minLength: 1 type: string required: - operatorFirstname - operatorLastname - operatorPhone type: object required: true responses: '201': content: application/json: schema: additionalProperties: false properties: data: additionalProperties: false properties: operator: additionalProperties: false description: The operator just created. properties: createdAt: description: When the operator was created. format: date-time type: string lastSignInAt: description: When the operator last signed in. format: date-time nullable: true type: string lastTenantID: description: The tenant the operator was last working in. nullable: true type: string operatorEmail: description: E-mail address (also the login identifier). type: string operatorFirstname: description: Given name. type: string operatorID: description: The operator identifier. type: string operatorLastname: description: Family name. type: string operatorMeta: additionalProperties: {} description: Arbitrary metadata attached to the operator. type: object operatorPhone: description: Phone number, when set. nullable: true type: string operatorPhoto: description: Avatar URL, when set. nullable: true type: string operatorRoles: description: Platform-wide roles, e.g. `superuser`. items: type: string type: array operatorSettings: additionalProperties: false description: Notification preferences and push tokens. properties: notificationSettings: additionalProperties: false properties: allDisabled: description: >- Master switch — silences every notification for this operator. type: boolean allowSounds: description: >- Whether the web app may play a notification sound. type: boolean onMessageInbound: description: Notify on an inbound message. type: boolean onOperatorMentioned: description: Notify when mentioned in an internal note. type: boolean onSessionCreated: description: Notify when a session is opened. type: boolean onSessionQueued: description: Notify when a session enters the queue. type: boolean tokens: additionalProperties: false description: Push tokens registered per platform. properties: mobile: description: >- FCM token of the mobile app, when one is registered. nullable: true type: string web: description: >- FCM token of the browser session, when one is registered. nullable: true type: string required: - web - mobile type: object required: - allDisabled - onSessionCreated - onSessionQueued - onMessageInbound - allowSounds - tokens type: object required: - notificationSettings type: object organizationID: description: The Talqui organization this operator belongs to. type: string updatedAt: description: When the operator was last updated. format: date-time type: string required: - operatorID - operatorFirstname - operatorLastname - operatorPhoto - operatorPhone - operatorEmail - operatorRoles - operatorMeta - lastSignInAt - lastTenantID - createdAt - updatedAt type: object required: - operator type: object required: - data type: object description: Response for status 201. '400': content: application/json: schema: properties: errors: items: $ref: '#/components/schemas/RequestValidationError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: >- RequestValidationError (error_code 1002): request body fails schema validation. '401': content: application/json: schema: properties: errors: items: oneOf: - $ref: '#/components/schemas/UnauthorizedError' - $ref: '#/components/schemas/InvalidTokenError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: >- UnauthorizedError (error_code 1003): missing access token. | InvalidTokenError (error_code 1028): not an access token, or it is expired or revoked. '403': content: application/json: schema: properties: errors: items: $ref: '#/components/schemas/EmailNotVerifiedError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: >- EmailNotVerifiedError (error_code 1853): the account's e-mail is not verified. '409': content: application/json: schema: properties: errors: items: oneOf: - $ref: '#/components/schemas/OperatorAlreadyOnboardedError' - $ref: '#/components/schemas/OperatorLinkPendingError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: >- OperatorAlreadyOnboardedError (error_code 1851): the account already has an operator; the body also carries it in `data.operator`. | OperatorLinkPendingError (error_code 1852): an operator with this e-mail exists but is not linked to this account yet. '500': content: application/json: schema: properties: errors: items: $ref: '#/components/schemas/UnknownError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: >- UnknownError (error_code 5999): Unexpected internal error not otherwise documented for this endpoint. components: schemas: RequestValidationError: additionalProperties: false properties: error: enum: - RequestValidationError type: string error_code: enum: - 1002 type: number fields: items: additionalProperties: false properties: allowed: type: string field: type: string received: type: string required: - field - received - allowed type: object type: array message: example: Invalid request data. type: string statusCode: enum: - 400 type: number required: - statusCode - error - error_code - message - fields type: object UnauthorizedError: additionalProperties: false properties: error: enum: - UnauthorizedError type: string error_code: enum: - 1003 type: number message: example: You are not authorized to perform this request. type: string statusCode: enum: - 401 type: number required: - statusCode - error - error_code - message type: object InvalidTokenError: additionalProperties: false properties: error: enum: - InvalidTokenError type: string error_code: enum: - 1028 type: number message: example: Connection token is invalid or expired. type: string statusCode: enum: - 401 type: number required: - statusCode - error - error_code - message type: object EmailNotVerifiedError: additionalProperties: false properties: error: enum: - EmailNotVerifiedError type: string error_code: enum: - 1853 type: number message: example: Verify your e-mail address first. type: string statusCode: enum: - 403 type: number required: - statusCode - error - error_code - message type: object OperatorAlreadyOnboardedError: additionalProperties: false properties: error: enum: - OperatorAlreadyOnboardedError type: string error_code: enum: - 1851 type: number message: example: This identity already has an operator. type: string statusCode: enum: - 409 type: number required: - statusCode - error - error_code - message type: object OperatorLinkPendingError: additionalProperties: false properties: error: enum: - OperatorLinkPendingError type: string error_code: enum: - 1852 type: number message: example: >- An operator with this e-mail exists but is not linked to this identity yet. type: string statusCode: enum: - 409 type: number required: - statusCode - error - error_code - message type: object UnknownError: additionalProperties: false properties: error: enum: - UnknownError type: string error_code: enum: - 5999 type: number message: example: For some unknown reason your request has not succeeded. type: string statusCode: enum: - 500 type: number required: - statusCode - error - error_code - message type: object ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.