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

# Create an Entity Onboarding Request

> Creates an Entity Onboarding Request and returns the created Entity Onboarding Request.

### Important Parameters

<ParamField body="type" type="enum<string>" required>
  Specify the type of device or vehicle that you want to connect with.\
  Available options are `Battery`, `ChargePoint`, `EV`, `HeatPump`, `SolarPlant`, `RetrofitMeter`, `Meter`, and `Inverter`.
</ParamField>

<ParamField body="brand" type="string" required>
  Specify the manufacturer (for example: “Audi” or “Huawei”) of the device or vehicle you want to connect with.
  [List all available Entity brands](/api-reference/endpoint/onboarding-api/onboard-entities/retrieve-available-entity-brands-and-types) to learn about the available options.
</ParamField>

<ParamField body="identifier" type="string">
  A unique identifier asigned by the vehicle or device manufacturer.
</ParamField>

### Additional Parameters

Some manufacturers may require additional identifiers or special parameters to be set to complete this request. Read our [dedicated onboarding guides](/guides/onboarding-requests) for more information.

## Detailed Endpoint Reference


## OpenAPI

````yaml post /v1/onboarding/entities
openapi: 3.0.4
info:
  title: Connect Onboarding API
  description: Provides endpoints to process onboarding.
  version: '1.0'
servers:
  - url: https://api.traxes.io/connect
security:
  - bearerAuth: []
tags:
  - name: Collective onboarding
    description: Manages Collective Onboarding in the platform
  - name: Entity onboarding
    description: Manages Entity onboarding in the platform
  - name: Guided entity onboarding
    description: Add an entity to the platform through a guided onboarding session
paths:
  /v1/onboarding/entities:
    post:
      tags:
        - Entity onboarding
      summary: Create an Entity Onboarding Request
      description: >-
        Creates an Entity Onboarding Request and returns the created Entity
        Onboarding Request.
      operationId: post-postentityonboardingasync
      requestBody:
        description: |-
          The Entity Onboarding Request.
                      
                       The entity can be placed in a Collective.
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/Connect.Service.Onboarding.App.Models.V1.EntityOnboardingRequest
          text/json:
            schema:
              $ref: >-
                #/components/schemas/Connect.Service.Onboarding.App.Models.V1.EntityOnboardingRequest
          application/*+json:
            schema:
              $ref: >-
                #/components/schemas/Connect.Service.Onboarding.App.Models.V1.EntityOnboardingRequest
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Connect.Service.Onboarding.App.Models.V1.OnboardingRequest
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Connect.Errors.Results.ConnectApiErrorResult
components:
  schemas:
    Connect.Service.Onboarding.App.Models.V1.EntityOnboardingRequest:
      required:
        - brand
        - type
      type: object
      properties:
        collectiveId:
          type: string
          description: The id of the Collective the Entity will be added to.
          format: uuid
          nullable: true
        pairingCode:
          type: string
          description: The pairing code of the Entity
          nullable: true
        associatedEmail:
          type: string
          description: The associated email address used to onboard the Entity
          nullable: true
        brand:
          type: string
          description: The brand of the Entity
          nullable: true
        name:
          type: string
          description: The name of the Entity
          nullable: true
        owner:
          type: string
          description: The owner of the Entity
          format: uuid
          nullable: true
        properties:
          description: The custom properties of the Entity
          nullable: true
        identifier:
          type: string
          description: The identifier of the Entity
          nullable: true
        returnUrl:
          type: string
          description: >-
            Represents the url where the user will be redirected to after
            completing the consent flow on the OEM page
          nullable: true
        track:
          type: string
          description: The track of the Entity
          nullable: true
        type:
          $ref: >-
            #/components/schemas/Connect.Service.Onboarding.Core.Models.Data.EntityType
      additionalProperties: false
      description: Represents a request to onboard an Entity
    Connect.Service.Onboarding.App.Models.V1.OnboardingRequest:
      type: object
      properties:
        action:
          $ref: >-
            #/components/schemas/Connect.Service.Onboarding.App.Models.V1.OnboardingRequestAction
        created:
          type: string
          description: The date and time the onboarding request was created.
          format: date-time
        data:
          $ref: >-
            #/components/schemas/Connect.Service.Onboarding.App.Models.V1.Data.OnboardingRequestData
        id:
          type: string
          description: The id of the onboarding request
          format: uuid
        principalId:
          type: string
          description: The id of the principal that initiated the onboarding request
          format: uuid
        requestType:
          $ref: >-
            #/components/schemas/Connect.Service.Onboarding.Core.Models.OnboardingRequestType
        returnUrl:
          type: string
          description: >-
            The url where the User will be redirected to after completing the
            consent flow on the OEM page.
          nullable: true
        status:
          $ref: >-
            #/components/schemas/Connect.Service.Onboarding.Core.Models.OnboardingStatus
        errors:
          type: array
          items:
            $ref: >-
              #/components/schemas/Connect.Service.Onboarding.App.Models.V1.OnboardingRequestError
          description: Errors that occurred during the processing of the onboarding request
          nullable: true
      additionalProperties: false
      description: Represents an onboarding request
    Connect.Errors.Results.ConnectApiErrorResult:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Connect.Errors.Results.ConnectApiError'
          nullable: true
      additionalProperties: false
    Connect.Service.Onboarding.Core.Models.Data.EntityType:
      enum:
        - Battery
        - ChargePoint
        - EV
        - HeatPump
        - SolarPlant
        - RetrofitMeter
        - Meter
        - Inverter
      type: string
    Connect.Service.Onboarding.App.Models.V1.OnboardingRequestAction:
      type: object
      properties:
        documentationLink:
          type: string
          description: A link to documentation explaining the user how to proceed
          format: uri
          nullable: true
        redirectLink:
          type: string
          description: A link to redirect the user to
          format: uri
          nullable: true
        type:
          $ref: >-
            #/components/schemas/Connect.Service.Onboarding.Core.Models.OnboardingRequestActionType
      additionalProperties: false
      description: Represents an action for an onboarding request
    Connect.Service.Onboarding.App.Models.V1.Data.OnboardingRequestData:
      type: object
      properties:
        collective:
          $ref: >-
            #/components/schemas/Connect.Service.Onboarding.App.Models.V1.Data.Collective
        entity:
          $ref: >-
            #/components/schemas/Connect.Service.Onboarding.App.Models.V1.Data.Entity
      additionalProperties: false
      description: Represents the data of an onboarding request
    Connect.Service.Onboarding.Core.Models.OnboardingRequestType:
      enum:
        - Collective
        - Entity
      type: string
    Connect.Service.Onboarding.Core.Models.OnboardingStatus:
      enum:
        - Canceled
        - Failed
        - InProgress
        - Pending
        - Succeeded
      type: string
    Connect.Service.Onboarding.App.Models.V1.OnboardingRequestError:
      type: object
      properties:
        code:
          type: string
          description: The code of the error
          nullable: true
        message:
          type: string
          description: The message of the error
          nullable: true
      additionalProperties: false
      description: An error that occurred during the onboarding request
    Connect.Errors.Results.ConnectApiError:
      type: object
      properties:
        code:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
      additionalProperties: false
    Connect.Service.Onboarding.Core.Models.OnboardingRequestActionType:
      enum:
        - Consent
        - Redirect
      type: string
    Connect.Service.Onboarding.App.Models.V1.Data.Collective:
      type: object
      properties:
        id:
          type: string
          description: The id of the Collective
          format: uuid
        name:
          type: string
          description: The name of the Collective
          nullable: true
        owner:
          type: string
          description: The owner of the Collective
          format: uuid
        properties:
          description: The custom properties of the Collective
          nullable: true
        type:
          $ref: >-
            #/components/schemas/Connect.Service.Onboarding.Core.Models.Data.CollectiveType
      additionalProperties: false
      description: Represents data required to onboard a Collective
    Connect.Service.Onboarding.App.Models.V1.Data.Entity:
      type: object
      properties:
        collectiveId:
          type: string
          description: The id of the Collective the Entity belongs to.
          format: uuid
          nullable: true
        id:
          type: string
          description: The id of the Entity
          format: uuid
        information:
          $ref: >-
            #/components/schemas/Connect.Service.Onboarding.App.Models.V1.Data.EntityInformation
        owner:
          type: string
          description: The id of the owner of the Entity
          format: uuid
        properties:
          description: The custom properties of the Entity
          nullable: true
        reference:
          $ref: >-
            #/components/schemas/Connect.Service.Onboarding.App.Models.V1.Data.EntityReference
        systemProperties:
          description: The system properties of the Entity
          nullable: true
        type:
          $ref: >-
            #/components/schemas/Connect.Service.Onboarding.Core.Models.Data.EntityType
      additionalProperties: false
      description: Represents data required to onboard an Entity
    Connect.Service.Onboarding.Core.Models.Data.CollectiveType:
      enum:
        - Household
        - Fleet
        - SolarFarm
        - VirtualPowerPlant
      type: string
    Connect.Service.Onboarding.App.Models.V1.Data.EntityInformation:
      type: object
      properties:
        type:
          $ref: >-
            #/components/schemas/Connect.Service.Onboarding.Core.Models.Data.EntityType
        brand:
          type: string
          description: The brand of an Entity
          nullable: true
        identifier:
          type: string
          description: The identifier of an Entity
          nullable: true
        pairingCode:
          type: string
          description: The pairing code of an Entity
          nullable: true
        associatedEmail:
          type: string
          description: The associated email address used for onboarding an Entity
          nullable: true
        name:
          type: string
          description: The name of an Entity
          nullable: true
        track:
          type: string
          description: The track for an Entity
          nullable: true
      additionalProperties: false
      description: Represents information about an Entity
    Connect.Service.Onboarding.App.Models.V1.Data.EntityReference:
      type: object
      properties:
        brand:
          type: string
          description: The brand of the Entity
          nullable: true
        type:
          type: string
          description: The model of the Entity
          nullable: true
        identifier:
          type: string
          description: The reference of the Entity
          nullable: true
      additionalProperties: false
      description: A reference to an Entity
  securitySchemes:
    bearerAuth:
      type: http
      description: Access Token Authentication
      scheme: bearer
      bearerFormat: JWT

````