> ## Documentation Index > Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt > Use this file to discover all available pages before exploring further. # Start session > Starts a stopped session or retries a session whose runtime failed. A hosted paid number must reserve credit before connecting; insufficient available credit returns 402. A new paid window is charged only after the messaging connection succeeds. The identifier may be the session UUID or stable session slug. Requires `sessions:manage`. Project tokens only access resources in their own project. A start request creates an operation. Keep its operation ID and [check the operation](/api-reference/platform/operations/get-account-operation) until it reaches a terminal status. A pending or running operation does not mean the number is connected. If a start takes longer than expected, check the existing operation and the number's connection status before submitting another start. Include the operation ID when contacting support so they can inspect the same request. ## OpenAPI ````yaml api-reference/features/numbers.json POST /platform/sessions/{sessionId}/start openapi: 3.0.3 info: title: Numbers and sessions API methods version: 1.0.0 description: >- Task-focused numbers and sessions methods across supported Polymorfa connection types. servers: [] security: [] paths: /platform/sessions/{sessionId}/start: post: tags: - Sessions summary: Start session description: >- Starts a stopped session or retries a session whose runtime failed. A hosted paid number must reserve credit before connecting; insufficient available credit returns 402. A new paid window is charged only after the messaging connection succeeds. The identifier may be the session UUID or stable session slug. Requires `sessions:manage`. Project tokens only access resources in their own project. operationId: managementStartPlatformSession parameters: - name: sessionId in: path required: true description: |- Database session UUID or stable session slug. **Value constraints** | Constraint | Accepted input | | --- | --- | | String length | `1` through `64` characters | schema: $ref: '#/components/schemas/management__SessionIdentifier' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/management__SessionProjectContext' responses: '200': description: Success headers: X-Request-Id: schema: type: string description: Stable request correlation identifier. Polymorfa-Version: schema: type: string description: API version applied to this response. content: application/json: schema: type: object additionalProperties: false properties: data: allOf: - $ref: '#/components/schemas/management__SessionStartResult' description: Structured data carried by this object. required: - data '401': $ref: '#/components/responses/management__Unauthorized' '402': $ref: '#/components/responses/management__BillingCreditRequired' '403': $ref: '#/components/responses/management__Forbidden' '404': $ref: '#/components/responses/management__NotFound' '409': $ref: '#/components/responses/management__Conflict' '500': $ref: '#/components/responses/management__InternalError' security: - management__ApiKeyAuth: [] servers: - url: https://api.polymorfa.com components: schemas: management__SessionIdentifier: type: string minLength: 1 maxLength: 64 description: Database session UUID or stable session slug. management__SessionProjectContext: type: object additionalProperties: false properties: projectId: allOf: - $ref: '#/components/schemas/management__ProjectId' description: |- Identifier of the Polymorfa project that owns this resource. **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `uuid` | management__SessionStartResult: type: object additionalProperties: false properties: starting: type: boolean enum: - true description: |- Whether starting. **Allowed values** | Value | Meaning | | --- | --- | | `true` | True. | sessionId: type: string format: uuid description: |- Identifier of the connected Polymorfa session. **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `uuid` | required: - starting - sessionId management__ProjectId: type: string format: uuid description: >- Project UUID. Optional where an operation can infer or search team scope; required where the operation creates a project-owned resource. management__ErrorEnvelope: type: object required: - error - data - docs properties: error: type: object required: - type - code - message - param - request_id properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - conflict_error - rate_limit_error - api_error - upstream_error description: |- Type discriminator for this object. **Allowed values** | Value | Meaning | | --- | --- | | `invalid_request_error` | Invalid request error. | | `authentication_error` | Authentication error. | | `permission_error` | Permission error. | | `conflict_error` | Conflict error. | | `rate_limit_error` | Rate limit error. | | `api_error` | Api error. | | `upstream_error` | Upstream error. | code: type: string description: Stable failure code. Use this value for programmatic handling. message: type: string description: Safe explanation of the failure. param: type: string nullable: true description: |- Invalid request field, or null when no field applies. **Accepted alternatives** | Alternative | Accepted input | | --- | --- | | Alternative 1 | Type: `string` | | Alternative 2 | `null` | request_id: type: string description: >- Matches the X-Request-Id response header. Include it when you contact support. request_log_url: type: string format: uri description: >- Console page that shows this request. Returned only to organization and project credentials whose request was logged. **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `uri` | description: Error details returned when the operation fails. data: type: string nullable: true enum: - null description: |- Always null for a failed request. **Allowed values** | Value | Meaning | | --- | --- | | `null` | Null. | **Accepted alternatives** | Alternative | Accepted input | | --- | --- | | Alternative 1 | Type: `string` | | Alternative 2 | `null` | docs: type: string format: uri description: |- Documentation link to this failure code. **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `uri` | responses: management__Unauthorized: description: Missing/invalid credential for this audience. headers: X-Request-Id: schema: type: string description: Stable request correlation identifier. Polymorfa-Version: schema: type: string description: API version applied to this response. content: application/json: schema: $ref: '#/components/schemas/management__ErrorEnvelope' management__BillingCreditRequired: description: >- The paid number could not reserve sufficient available credit. Add credit to your team before starting it. headers: X-Request-Id: schema: type: string description: Stable request correlation identifier. Polymorfa-Version: schema: type: string description: API version applied to this response. content: application/json: schema: $ref: '#/components/schemas/management__ErrorEnvelope' management__Forbidden: description: Authenticated but lacks the required scope/role/audience. headers: X-Request-Id: schema: type: string description: Stable request correlation identifier. Polymorfa-Version: schema: type: string description: API version applied to this response. content: application/json: schema: $ref: '#/components/schemas/management__ErrorEnvelope' management__NotFound: description: >- The requested resource was not found inside the authenticated team or project scope. headers: X-Request-Id: schema: type: string description: Stable request correlation identifier. Polymorfa-Version: schema: type: string description: API version applied to this response. content: application/json: schema: $ref: '#/components/schemas/management__ErrorEnvelope' management__Conflict: description: The request conflicts with the resource's current state. headers: X-Request-Id: schema: type: string description: Stable request correlation identifier. Polymorfa-Version: schema: type: string description: API version applied to this response. content: application/json: schema: $ref: '#/components/schemas/management__ErrorEnvelope' management__InternalError: description: >- The session-control publisher or testing-number persistence path is temporarily unavailable. headers: X-Request-Id: schema: type: string description: Stable request correlation identifier. Polymorfa-Version: schema: type: string description: API version applied to this response. content: application/json: schema: $ref: '#/components/schemas/management__ErrorEnvelope' securitySchemes: management__ApiKeyAuth: type: http scheme: bearer description: >- Send your team API key or project token as `Authorization: Bearer `. The credential must have the required permissions. Project tokens can access only their own project. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.