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

# Numbers - Port In

> **Prerequisites:**
- **Required:** Bearer token — `POST /v1.0/oauth2/tokens`
- **Recommended:** Confirm the number is portable first — `POST /v1.0/numbers/portin/eligibility`
- **Required:** Losing carrier name, account number, account password, and subscriber billing address

---

Transfer an existing phone number from another carrier into your Telegent account. Before submitting a port-in, run the Port-In Eligibility check to confirm the number can be ported. You will need the losing carrier name, account number, account password, and the subscriber's billing address for LNP (Local Number Portability) compliance.

**What this does:** Submits the port request to the carrier and returns an `OrderId` with an initial status of `Pending`. Monitor the order using the `OrderId`. Port requests typically take 1-5 business days to complete.

**Next steps:**
- Track the port order status — `GET /v1.0/numbers/order`
- Cancel if needed — `POST /v1.0/numbers/portin/cancel`



## OpenAPI

````yaml /api-reference/openapi.json post /v1.0/numbers/portin
openapi: 3.0.3
info:
  title: mPaaS Core APIs
  version: 1.0.8
  description: >-
    The Telegent mPaaS (Mobile Platform as a Service) API gives you full
    programmatic control over mobile phone numbers, messaging, voice routing,
    subscribers, and account management. Use these APIs to provision MVNO and
    IoT numbers, send and receive SMS/MMS, configure intelligent call routing,
    manage subscriber accounts, and apply AI Guardian controls. All requests
    require a Bearer token obtained from the Authentication endpoint. For
    support, visit https://support.telegent.com/support/home
  contact:
    name: Support
    email: support@telegent.com
  termsOfService: https://telegent.com/terms
  license:
    name: Use under LICX
    url: https://telegent.com/license
servers:
  - url: https://api.telegent.com/v1.0
security:
  - BearerAuth: []
tags:
  - name: OAuth2
  - name: AI Guardian
  - name: Accounts
  - name: Distributors
  - name: Message
  - name: Numbers
  - name: Voicemail
  - name: Packages
  - name: Products
  - name: Schedules
  - name: Services
  - name: Sims
  - name: Subscribers
  - name: Subscriptions
  - name: Voice
  - name: Workgroups
paths:
  /v1.0/numbers/portin:
    post:
      tags:
        - Numbers
      summary: Numbers - Port In
      description: >-
        **Prerequisites:**

        - **Required:** Bearer token — `POST /v1.0/oauth2/tokens`

        - **Recommended:** Confirm the number is portable first — `POST
        /v1.0/numbers/portin/eligibility`

        - **Required:** Losing carrier name, account number, account password,
        and subscriber billing address


        ---


        Transfer an existing phone number from another carrier into your
        Telegent account. Before submitting a port-in, run the Port-In
        Eligibility check to confirm the number can be ported. You will need the
        losing carrier name, account number, account password, and the
        subscriber's billing address for LNP (Local Number Portability)
        compliance.


        **What this does:** Submits the port request to the carrier and returns
        an `OrderId` with an initial status of `Pending`. Monitor the order
        using the `OrderId`. Port requests typically take 1-5 business days to
        complete.


        **Next steps:**

        - Track the port order status — `GET /v1.0/numbers/order`

        - Cancel if needed — `POST /v1.0/numbers/portin/cancel`
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - PortInNumber
                - CurrentCarrierName
                - CurrentAccountNumber
                - CurrentAccountPassword
                - CurrentBillingAddress
              properties:
                PortInNumber:
                  type: string
                  description: Phone number to port in (E.164 format)
                  example: '+11234567890'
                CurrentCarrierName:
                  type: string
                  description: Name of the losing carrier
                  example: Company LLC
                CurrentAccountNumber:
                  type: string
                  description: Account number with current carrier
                  example: '4651234567'
                CurrentAccountPassword:
                  type: string
                  description: Account PIN/password with current carrier
                  example: '0550'
                CurrentBillingAddress:
                  type: object
                  required:
                    - Street1
                    - City
                    - State
                    - Zip
                  properties:
                    Street1:
                      type: string
                      example: 123 N Adddress Way
                    Street2:
                      type: string
                      example: Suite 010
                    City:
                      type: string
                      example: Townsville
                    State:
                      type: string
                      example: UT
                    Zip:
                      type: string
                      example: '84048'
                ICCID:
                  type: string
                  description: SIM card ICCID (optional)
                  example: 8901240397190557414F
                TargetPortinClassification:
                  type: string
                  enum:
                    - mvno
                    - iot
                  description: Classification type for the port-in
                  example: mvno
                SubscriberName:
                  type: string
                  description: Name of the subscriber (optional)
                  example: John Doe
      responses:
        '200':
          description: Success — returns the port-in order ID and initial status
          content:
            application/json:
              schema:
                type: object
              examples:
                example:
                  value:
                    OrderId: JNOID-aabbde7a-....-....-....-............
                    OrderDate: '2025-05-14T18:00:00.0000000+00:00'
                    Status: Pending
                    PhoneNumber: '+11234567890'
                    ICCID: '12345678900987654321'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/BadRequest_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest_Result'
              examples:
                example:
                  value:
                    StatusCode: 400
                    Message: >-
                      Bad request: one or more required fields are missing or
                      contain an invalid value.
            text/json:
              schema:
                $ref: '#/components/schemas/BadRequest_Result'
        '401':
          description: Unauthorized
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Unauthorized_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized_Result'
              examples:
                example:
                  value:
                    StatusCode: 401
                    Message: >-
                      Unauthorized: Bearer token is missing, expired, or
                      invalid. Re-authenticate via POST /v1.0/oauth2/tokens.
            text/json:
              schema:
                $ref: '#/components/schemas/Unauthorized_Result'
        '403':
          description: Forbidden
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Forbidden_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden_Result'
              examples:
                example:
                  value:
                    StatusCode: 403
                    Message: >-
                      Forbidden: your token does not have permission to access
                      this resource. Check the ApiEndpoint scope.
            text/json:
              schema:
                $ref: '#/components/schemas/Forbidden_Result'
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/NotFound_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound_Result'
              examples:
                example:
                  value:
                    StatusCode: 404
                    Message: >-
                      Not found: the requested resource does not exist or
                      belongs to a different account.
            text/json:
              schema:
                $ref: '#/components/schemas/NotFound_Result'
        '405':
          description: Method Not Allowed
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/MethodNotAllowed_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowed_Result'
              examples:
                example:
                  value:
                    StatusCode: 405
                    Message: >-
                      Method not allowed: verify the HTTP method required for
                      this endpoint.
            text/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowed_Result'
        '408':
          description: Request Timeout
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/RequestTimeout_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/RequestTimeout_Result'
              examples:
                example:
                  value:
                    StatusCode: 408
                    Message: >-
                      Request timeout: the server did not receive a complete
                      request within the allowed time. Retry with exponential
                      backoff.
            text/json:
              schema:
                $ref: '#/components/schemas/RequestTimeout_Result'
        '429':
          description: Too Many Requests
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/TooManyRequests_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests_Result'
              examples:
                example:
                  value:
                    StatusCode: 429
                    Message: >-
                      Too many requests: rate limit exceeded. Slow your request
                      cadence and retry after a short delay.
            text/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests_Result'
        '500':
          description: Server Error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/InternalServerError_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError_Result'
              examples:
                example:
                  value:
                    StatusCode: 500
                    Message: >-
                      Internal server error: an unexpected error occurred. If
                      the problem persists contact support@telegent.com.
            text/json:
              schema:
                $ref: '#/components/schemas/InternalServerError_Result'
        '503':
          description: Service Unavailable
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable_Result'
              examples:
                example:
                  value:
                    StatusCode: 503
                    Message: >-
                      Service unavailable: the API is temporarily unavailable.
                      Retry after a short delay.
            text/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable_Result'
        '504':
          description: Gateway Timeout
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/GatewayTimeout_Result'
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayTimeout_Result'
              examples:
                example:
                  value:
                    StatusCode: 504
                    Message: >-
                      Gateway timeout: an upstream service did not respond in
                      time. Retry with exponential backoff.
            text/json:
              schema:
                $ref: '#/components/schemas/GatewayTimeout_Result'
      x-codeSamples:
        - lang: JSON
          source: |-
            {
              "PortInNumber": "+15555551234",
              "ICCID": "8901240397190195850",
              "CurrentCarrierName": "Telegent",
              "CurrentAccountNumber": "46512222",
              "CurrentAccountPassword": "0000",
              "TargetPortinClassification": "mvno",
              "SubscriberName": "Telegent",
              "CurrentBillingAddress": {
                "Street1": "2701 N Thanksgiving Way",
                "Street2": "Suite 202",
                "City": "Lehi",
                "State": "UT",
                "Zip": "84043"
              }
            }
        - lang: cURL
          source: |-
            curl -X POST https://api.telegent.com/v1.0/numbers/portin \
              -H 'Authorization: Bearer YOUR_TOKEN' \
              -H 'Content-Type: application/json' \
              -d '{
                "PortInNumber": "+15555551234",
                "ICCID": "8901240397190195850",
                "CurrentCarrierName": "Telegent",
                "CurrentAccountNumber": "46512222",
                "CurrentAccountPassword": "0000",
                "TargetPortinClassification": "mvno",
                "SubscriberName": "Telegent",
                "CurrentBillingAddress": {"Street1": "2701 N Thanksgiving Way", "Street2": "Suite 202", "City": "Lehi", "State": "UT", "Zip": "84043"}
              }'
components:
  schemas:
    BadRequest_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false
    Unauthorized_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false
    Forbidden_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false
    NotFound_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false
    MethodNotAllowed_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false
    RequestTimeout_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false
    TooManyRequests_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false
    InternalServerError_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false
    ServiceUnavailable_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false
    GatewayTimeout_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
        Message:
          type: string
          nullable: true
      additionalProperties: false

````