> ## Documentation Index > Fetch the complete documentation index at: https://docs.provisionapp.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a conversation > Create a new conversation for a client through the same pipeline that backs the portal. The client (`requesterId`) is the requester, not the message author. Provide `message` to post an initial private (internal) note, authored by `senderId` (a platform user) or the system bot when omitted. `customProperties` accepts the custom properties defined for your partner, keyed by property id; send `null` to clear one. Requires the `conversation:write` scope. ## OpenAPI ````yaml /openapi.yaml post /v1/conversation/submit openapi: 3.1.0 info: title: ProVision Public API version: 1.0.0 description: >- Use the ProVision Public API to integrate with ProVision conversations, clients, users, and addresses. All endpoints accept and return JSON, are authenticated with an `x-api-key` header, and are scoped to a single partner tenant. contact: email: support@onevisionresources.com name: OneVision Resources Support license: name: Proprietary servers: - url: https://connect.provisionapp.io description: Production security: [] paths: /v1/conversation/submit: post: tags: - conversation summary: Create a conversation description: >- Create a new conversation for a client through the same pipeline that backs the portal. The client (`requesterId`) is the requester, not the message author. Provide `message` to post an initial private (internal) note, authored by `senderId` (a platform user) or the system bot when omitted. `customProperties` accepts the custom properties defined for your partner, keyed by property id; send `null` to clear one. Requires the `conversation:write` scope. operationId: submitConversation requestBody: content: application/json: schema: $ref: '#/components/schemas/SubmitConversationPayload' responses: '201': description: Created conversation content: application/json: schema: $ref: '#/components/schemas/SubmitConversationResult' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - OpenApiKeyAuth: [] components: schemas: SubmitConversationPayload: type: object properties: subject: type: string type: $ref: '#/components/schemas/ConversationType' status: $ref: '#/components/schemas/ConversationStatus' urgency: $ref: '#/components/schemas/ConversationUrgency' snoozeUntil: type: string format: date-time assigneeId: $ref: '#/components/schemas/UserId' conversationAssigneeGroupId: type: string format: uuid requesterId: $ref: '#/components/schemas/ClientId' senderId: $ref: '#/components/schemas/UserId' message: type: object properties: body: type: string required: - body additionalProperties: false customProperties: $ref: '#/components/schemas/CustomPropertiesWrite' required: - subject - requesterId additionalProperties: false SubmitConversationResult: type: object properties: conversation: $ref: '#/components/schemas/Conversation' message: allOf: - $ref: '#/components/schemas/SubmitConversationMessage' - type: - object - 'null' required: - conversation - message additionalProperties: false ErrorResponse: type: object properties: error: $ref: '#/components/schemas/ApiError' required: - error ConversationType: type: - string - 'null' enum: - support_ticket - member_services - non_support_event - null ConversationStatus: type: - string - 'null' enum: - new - open - snoozed - on_hold - solved - closed - null ConversationUrgency: type: - string - 'null' enum: - urgent - normal - low - life_safety - null UserId: type: string minLength: 1 description: >- Platform user id. Newer ids are `ovuid-`; legacy users may have bare (e.g. numeric) ids. example: ovuid-2b6d4d8e-9f1a-4b2c-8d4e-5f6011223344 ClientId: type: string pattern: ^ovcid-.*$ CustomPropertiesWrite: type: object additionalProperties: {} description: >- Custom property values, keyed by property id. Ids and value types come from the properties defined for your partner, so this object cannot be described field by field here: an unknown id or a value that does not match the property type is rejected with 400. Only the ids you send are modified — omit a property to leave it untouched. To clear one, send `null`; a blank string and an empty array count as empty too, for every property type alike. example: warranty_count: 5 region: east onsite_required: true Conversation: type: object properties: id: type: string friendlyId: type: string subject: type: string type: $ref: '#/components/schemas/ConversationType' snoozeUntil: type: - string - 'null' format: date-time createdAt: type: string format: date-time deletedAt: type: - string - 'null' format: date-time assigneeGroupUpdatedAt: type: - string - 'null' format: date-time assigneeUpdatedAt: type: - string - 'null' format: date-time conversationStatusUpdatedAt: type: - string - 'null' format: date-time lastMessageReceivedAt: type: - string - 'null' format: date-time requesterUpdatedAt: type: - string - 'null' format: date-time sites: type: - array - 'null' items: $ref: '#/components/schemas/ConversationSite' status: $ref: '#/components/schemas/ConversationStatus' urgency: $ref: '#/components/schemas/ConversationUrgency' assigneeId: type: - string - 'null' assignee: $ref: '#/components/schemas/ConversationAssignee' conversationAssigneeGroupId: type: - string - 'null' format: uuid conversationAssigneeGroup: $ref: '#/components/schemas/ConversationAssigneeGroup' requesterId: type: - string - 'null' format: uuid requester: $ref: '#/components/schemas/ConversationParticipant' participants: type: - array - 'null' items: $ref: '#/components/schemas/ConversationParticipant' labels: type: - array - 'null' items: type: string customProperties: $ref: '#/components/schemas/CustomProperties' required: - id - friendlyId - subject - type - snoozeUntil - createdAt - deletedAt - assigneeGroupUpdatedAt - assigneeUpdatedAt - conversationStatusUpdatedAt - lastMessageReceivedAt - requesterUpdatedAt - status - urgency - customProperties additionalProperties: false SubmitConversationMessage: type: object properties: id: type: string body: type: - string - 'null' isPrivate: type: - boolean - 'null' required: - id - body - isPrivate additionalProperties: false ApiError: type: object properties: code: type: string description: Machine-readable error code example: NOT_FOUND message: type: string description: Human-readable error description required: - code - message ConversationSite: type: object properties: id: type: string address1: type: - string - 'null' address2: type: - string - 'null' city: type: - string - 'null' state: type: - string - 'null' zip: type: - string - 'null' tosAccepted: type: string serviceLevel: $ref: '#/components/schemas/ServiceLevel' clientSegment: type: string cppExpDate: type: string format: date-time businessName: type: string brandId: type: string primaryClientId: type: string primaryProjectId: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time sla: type: number isMonitored: type: boolean required: - id - address1 - address2 - city - state - zip ConversationAssignee: type: - object - 'null' properties: id: type: string firstName: type: string lastName: type: string required: - id - firstName - lastName ConversationAssigneeGroup: type: - object - 'null' properties: conversationAssigneeGroupId: type: string format: uuid name: type: string required: - conversationAssigneeGroupId - name additionalProperties: false ConversationParticipant: anyOf: - type: object properties: id: type: string format: uuid identityId: type: string firstName: type: string lastName: type: string entityType: $ref: '#/components/schemas/ParticipantEntityType' email: type: - string - 'null' required: - id - identityId - firstName - lastName - entityType - type: object properties: id: type: string format: uuid name: type: string identityId: type: string entityType: $ref: '#/components/schemas/ParticipantEntityType' required: - id - name - identityId - entityType - type: 'null' CustomProperties: type: object additionalProperties: anyOf: - type: string - type: number - type: boolean - type: array items: type: string description: >- Custom property values, keyed by property id. Ids and value types come from the properties defined for your partner, so this object cannot be described field by field here — call the custom-property list endpoint to resolve an id to its name and type. A property never given a value takes the default configured for it, and is left out rather than returned as `null` when there is no default either. A value stored before its property was changed — an option renamed or removed, the type switched — is returned as stored, so it may not match the type the property has today; an absent key is the only reliable sign that nothing is set. example: warranty_count: 5 region: east onsite_required: true ServiceLevel: type: string enum: - Inactive - Non-Member - Warranty Essentials - CPP Essentials Plus - Essentials Plus - CPP Priority - Priority - CPP Proactive - Proactive - CPP Signature - Signature - Secure - OV - Internal - Legacy ParticipantEntityType: type: - string - 'null' enum: - unknown - client - platform_user - bot - rsm - null securitySchemes: OpenApiKeyAuth: type: apiKey in: header name: x-api-key description: Send the API key in the x-api-key header. ````