> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionage.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Start session

> Starts a charging session remotely. The request validates the station, charger, connector, and connector availability. If the supplied customerId does not exist, the API creates a minimal customer record before sending a start command to the charger. Optional auth_reference lets callers correlate this request with the session created later by the charger. A 200 response means the command was accepted for delivery; it does not confirm that charging has begun.



## OpenAPI

````yaml /api-reference/nexus/nexus-api-oas.json post /sessions/start
openapi: 3.0.3
info:
  title: Nexus API
  description: >-
    The Nexus API provides access to charging stations, chargers, connectors,
    tariffs, customers, and charging sessions for partner backend integrations.


    ## Integration model


    This API is designed for server-to-server use. End-user applications should
    access this data through the partner backend rather than calling these
    endpoints directly.


    ## Authentication


    Every request must include an `x-api-key` header containing a valid API key.
    Missing or unrecognized API keys are rejected with `401 Unauthorized`.


    ## IDs


    Stations, chargers, and tariffs use `id` as their public stable identifier.
    These identifiers are exactly 8 alphanumeric characters. Customers use `id`,
    an opaque identifier supplied by the partner system. Sessions use a numeric
    session ID. Connector IDs are 1-based positive integers within a charger;
    invalid connector path values return `404 Not Found`.


    ## Tariffs


    Tariffs use a structured pricing model with elements, price components, and
    optional restrictions. `tariffId` response fields reference public tariff
    identifiers and are omitted when no tariff applies.


    ## Pagination


    Paginated collection endpoints accept `limit` and `offset` query parameters.
    Missing, non-integer, zero, or negative `limit` values use the default limit
    of 100; values above 100 are clamped to 100. Missing, non-integer, or
    negative `offset` values use 0. The response body includes a `links` object
    with `next` and `prev` URLs. A link is `null` when that page does not exist.
    The total result count is returned in the `X-Total-Count` response header.
  version: 1.0.0
servers:
  - url: https://{host}/v1
    description: Environment-specific Nexus API base URL.
    variables:
      host:
        default: api.example.com
        description: Nexus API host provided during onboarding.
security:
  - ApiKeyAuth: []
tags:
  - name: Stations
  - name: Chargers
  - name: Connectors
  - name: Tariffs
  - name: Customers
  - name: Sessions
paths:
  /sessions/start:
    post:
      tags:
        - Sessions
      summary: Start session
      description: >-
        Starts a charging session remotely. The request validates the station,
        charger, connector, and connector availability. If the supplied
        customerId does not exist, the API creates a minimal customer record
        before sending a start command to the charger. Optional auth_reference
        lets callers correlate this request with the session created later by
        the charger. A 200 response means the command was accepted for delivery;
        it does not confirm that charging has begun.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartSessionRequest'
      responses:
        '200':
          description: Command accepted for delivery to the charger.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          description: >-
            Malformed JSON body; a required field is missing; stationId or
            chargerId is not 8 alphanumeric characters; connectorId is below 1;
            or auth_reference is blank.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            Station or charger not found (or the charger is not at that
            station), or connector not found on the charger.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            The connector is not in Preparing status (no vehicle plugged in);
            auth_reference already belongs to an existing session; another start
            request is already pending on the charger (retry after about 2
            minutes); the customer cannot start a session; or the charger is
            offline.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '500':
          description: Delivery to the charger failed, or an internal error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
components:
  schemas:
    StartSessionRequest:
      type: object
      required:
        - stationId
        - chargerId
        - connectorId
        - customerId
      properties:
        stationId:
          type: string
          pattern: ^[a-zA-Z0-9]{8}$
          description: >-
            Public station identifier. Exactly 8 alphanumeric characters
            (a-zA-Z0-9).
        chargerId:
          type: string
          pattern: ^[a-zA-Z0-9]{8}$
          description: >-
            Public charger identifier within that station. Exactly 8
            alphanumeric characters (a-zA-Z0-9).
        connectorId:
          type: integer
          minimum: 1
          description: Connector number on the charger to start the session on.
        customerId:
          type: string
          minLength: 1
          description: >-
            Customer identifier for the charging session. If no customer with
            this ID exists, a minimal customer is created.
        auth_reference:
          type: string
          minLength: 1
          description: >-
            Optional caller-generated unique reference. Must not be blank, and
            must not already belong to an existing session (409). If supplied,
            it can be used with GET /sessions?auth_reference=... to poll until
            the charger starts the session.
    MessageResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: >-
            Human-readable status message. Treat this value as informational and
            do not depend on exact wording.
    ErrorResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key issued during onboarding. Every request must supply a valid
        x-api-key header.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.