openapi: 3.1.0
info:
  title: Porting API
  description: Automated processing of port-in phone number operations
  version: '1.0'
  license:
    name: MIT
    url: https://www.sinch.com/toc
servers:
  - url: https://porting.api.sinch.com/v1/projects/{projectId}
    description: v1.0 of the porting API
    variables:
      projectId:
        description: The project with which you are working.
        default: YOUR_project_id
tags:
  - name: Port-in numbers
    description: >-
      You can create orders, check portability, and more.

      When you port in phone numbers to Sinch you need to make sure the numbers
      are portable, you can use the portability check to make sure the numbers
      are portable before creating an order.

      If a number is not portable the whole order will fail.

      When porting a number to Sinch you can either use the dashboard or the
      API, the API is recommended for larger orders and for automation.


      **Note:** For port orders of over 500 numbers, please contact the [support
      team](https://tickets.sinch.com/plugins/servlet/desk/portal/31/create/1572).


      The recommended way to port numbers to Sinch is to schedule the port, this
      means that you create an order and specify a desired port date and time,

      If you have more advanced needs like on-demand activation, you can read
      more about that in the [advanced porting
      section](https://developers.sinch.com/docs/numbers/api-reference/porting/advanced-porting/).


      ### Porting orders


      In general you work with porting orders, a porting order is the resource
      that keeps the number(s) status and progress in one place.


      Before creating port order you should check the portability of the numbers
      you want to port in, if a number is not portable the order will fail.


      ```json

      POST /portabilityChecks

      {
        "phoneNumbers": ["+12345678901"]
      }

      ```


      If the number is portable you can create an order like this:


      ```json

      POST v1/projects/{projectId}/orders/portIns
          {
            "desiredPortSchedule": {
              "desiredPortDate": "2024-09-25",
            },
            "phoneNumbers": [
              {
                "phoneNumber": "+12345678901",
                "voiceConfiguration": {
                  "type": "EST",
                  "trunkId": "123456"
                },
                "portOutInfo": {
                  "existingPortOutPin": "1234"
                },
                "endUser": {
                  "name": "John Doe",
                  "streetName": "Main St",
                  "streetNum": "123",
                  "city": "Anytown",
                  "state": "NY",
                  "zipCode": "12345"
                },
              }
            ]
          }
          ```

      #### Lifetime of a port order


      If everything is correct, the order run thru is life cycle and keep you
      updated on changes but hopefully nothing will change and the number will
      be ported in on the desired port date.

      If more information is needed from you, it will be communicated to you via
      the order notes and error statuses on the individual numbers. And you
      reply with a note or update your order with required information.


      It's not uncommon for a port order to be a few days or weeks in the
      making, so don't worry if you don't receive an update right away.


      ### Port-In phone numbers


      When you port in phone numbers to Sinch you need to make sure the numbers
      are portable, you can use the portability check to make sure the numbers
      are portable before creating an order.
  - name: Webhooks
    description: >-
      ## Webhooks for porting


      Sinch uses webhooks to notify you of events that happen in the porting
      system.


      You can configure webhooks for porting events in the porting defaults API
      or via the dashboard. Anytime a port is then made via the dashboard or we
      at Sinch trigger an update we will call your webhook url with the event
      type and a payload depending on event type.
  - name: Port-in settings
    description: Porting default settings
  - name: Advanced porting
    description: >-
      This section is for advanced porting operations, like on demand activating
      numbers, getting available numbers for activation, and more.

      If you are looking for basic porting operations like creating an order,
      checking portability, and more, please refer to the Port-in numbers
      section.


      ### Scheduled ports


      The recommended way to port numbers to Sinch is to schedule the port, this
      means that you create an order and specify a desired port date and time,

      this is the date you want the numbers to be ported in to Sinch
      automatically and we will sync with the loosing carrier to make sure the
      port is done on

      that date with minimal downtime for you and your customers.


      ### On demand ports


      If you need to control your self when a number is activated you can use on
      demand ports, that means as soon as the number is confirmed you can
      activate

      it when you want. And we take care of the rest. When using on demand ports
      you need to make sure the number is confirmed and released for activation.
      you can also choose

      to activate numbers on activation groups.


      ### Activation groups


      When you create a port in order we assign an activating group on the
      numbers, the grouping is by carrier so if you have a large port-in order
      from multiple different carriers

      you can group and look at the numbers by group to see status. Updates to
      port order usually comes on group basis and are confirmed ro rejected on
      carrier level.


      You can also use this as a way  to activate groups for on-demand
      activation.

      However we recommend you porting in numbers by carrier to make sure you
      get the best experience.


      ### On demand activation


      When you set up an order with onDemandActivation set to true, you can
      activate the numbers when you want. This is useful if you want to control
      when the numbers are activated.


      You can activate a whole order by calling
      `/orders/portins/{orderId}/activate` or you can activate a specific group
      of numbers by calling `/orders/portins/{orderId}/activate`

      with the phoneNumberGroup you find on the number. Please note that it is
      not possible to activate single numbers by order or activation group.
  - name: Error Messages
    description: >-
      ## Error Messages


      Request errors are returned as HTTP status codes. The following table
      lists the possible error codes and their meaning.


      The type will give you a general idea of why the operation failed, whereas
      the errorCode describes the issue in more detail. Below we list the
      error_codes for the API, segmented by their corresponding error_type.


      ## Http Error Codes


      ### 400 - Bad Request


      ```json

      {
        "code": "404",
        "error": "Bad Request",
        "message": "
          The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
          It could be invalid JSON, missing required fields, or other issues."
      }

      ```


      ### 401 - Unauthorized


      Empty body, or you have the wrong API key, secret, or project.


      ### 402 - Payment required


      ```json

      {
        "code": "402",
        "error": "Payment required",
        "message": "You have reached 0 balance on your account please make a payment."
      }

      ```



      ### 404 - Not found


      ```json

      {
        "code": "404",
        "error": "Not found",
        "message": "The resource is not found, not available, or does not exist."
      }

      ```


      ### 422 - Unprocessable Content (Invalid parameters)


      ```json

      {
        "code": "422",
        "error": "Invalid parameters",
        "message": "The request could not be understood by the server due to malformed syntax.
           The client SHOULD NOT repeat the request without modifications."
        details: {
          fieldViolations: [
            {
              field: "to",
              description: "The (+15551) is not a valid phone number"
            }
          ]

        }
      ```


      ### 429 Rate limit exceeded


      Rate limit exceeded, please back off and try again later. If you need
      higher rate please contact support.



      ### 500 - Internal Server Error


      Probably no body, but if there is a body it will look like this:


      ```json

      {
        "code": "500",
        "error": "Internal service error",
        "message": "Most likely a temporary issue, please try again later. If the problem persists, please back of on this request and contact support."
      }

      ```


      ## Error object


      Please note that the response code is probably the most important part of
      the response, but the error object will contain more information about the
      error.

      Not all errors return this object, and the `details` object is not always
      present.
security:
  - basicAuth: []
  - bearerAuth: []
paths:
  /configuration:
    post:
      operationId: createConfiguration
      tags:
        - Port-in settings
      summary: Create Configuration
      description: Create default Configuration for a given project
      requestBody:
        required: true
        description: Create Communication Configuration for a given project
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DefaultsConfiguration'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultsConfiguration'
    get:
      operationId: getConfiguration
      tags:
        - Port-in settings
      summary: Get Configuration
      description: Retrieve Notification Configuration for a given project
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultsConfiguration'
    put:
      operationId: updateConfiguration
      tags:
        - Port-in settings
      summary: Update configuration
      description: Update default configurations for a given project
      requestBody:
        required: true
        description: Update default configurations for a given project
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DefaultsConfiguration'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultsConfiguration'
  /portabilityChecks:
    post:
      tags:
        - Port-in numbers
      operationId: checkPortingAvailability
      summary: Porting availability
      description: >-
        Use this  before creating a order to make sure all numbers are available
        for port in to Sinch. Please note that if you try to port a number that
        is not portable the order will fail.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortabilityCheckRequest'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortabilityCheckResponse'
  /orders/portIns:
    post:
      operationId: orderPortIn
      tags:
        - Port-in numbers
      summary: Create port-in order
      description: >-
        Create an order to port phone numbers from another carrier into Sinch.
        Refer to the Port-In Status section for more information on port-in
        order updates.

        Please note that order will fail if you try to port numbers that are not
        portable, so you should always use the portability check before creating
        an order.


        Note: For port orders of over 500 numbers, please contact the [support
        team](https://tickets.sinch.com/plugins/servlet/desk/portal/31/create/1572).


        **Note:** In order to send SMS and MMS messages in the US using 10DLC
        phone numbers, all messages must be sent via an approved campaign. Your
        campaigns are managed under US 10DLC Campaigns in the SMS section. A
        number can be associated to an approved campaign after the port
        completes.
      requestBody:
        description: Order Port-In phone numbers
        $ref: '#/components/requestBodies/OrderPortInRequest'
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderBaseItem'
    get:
      tags:
        - Port-in numbers
      operationId: getPortInOrders
      summary: List port-in orders
      description: >-
        Retrieve a list of port-in based on the search parameters, you can also
        specify view here to get less detail
      parameters:
        - in: query
          name: orderId
          schema:
            type: number
          description: Search by the ID of the order.
        - in: query
          name: orderStatus
          schema:
            $ref: '#/components/schemas/OrderStatus'
          description: Search by the status of the order.
        - in: query
          name: customerOrderReference
          description: The reference you specified when creating the order.
          schema:
            type: string
        - in: query
          name: createdDateStart
          schema:
            type: string
            format: date-time
            example: '2024-09-24T12:00:00Z'
          description: >-
            Search by the created date. This query sets the start date of the
            search period. Formatted as
            [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601):
            `YYYY-MM-DDThh:mm:ss.SSSZ`.
        - in: query
          name: createdDateEnd
          schema:
            type: string
            format: date-time
            example: '2024-09-24T12:00:00Z'
          description: >-
            Search by the created date. This query sets the end date of the
            search period. Formatted as
            [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601):
            `YYYY-MM-DDThh:mm:ss.SSSZ`.
        - in: query
          name: phoneNumber
          description: Search by a phone number.
          schema:
            type: string
        - in: query
          name: focStartDate
          schema:
            type: string
            format: date-time
            example: '2024-09-24T12:00:00Z'
          description: >-
            Search by the firm order confirmation. This query sets the start
            date of the search period. Formatted as
            [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601):
            `YYYY-MM-DDThh:mm:ss.SSSZ`.
        - in: query
          name: focEndDate
          schema:
            type: string
            format: date-time
            example: '2024-09-24T12:00:00Z'
          description: >-
            Search by the firm order confirmation. This query sets the end date
            of the search period. Formatted as
            [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601):
            `YYYY-MM-DDThh:mm:ss.SSSZ`.
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      orders:
                        type: array
                        items:
                          $ref: '#/components/schemas/OrderListItem'
                  - $ref: '#/components/schemas/Pagination'
  /orders/portIns/{orderId}/availableActivations:
    get:
      operationId: getPortInAvailableActivation
      tags:
        - Advanced porting
      description: >-
        Retrieve Port-In Order Available Activation Groups

        This operation allows you to get a list of phone number groups currently
        available for activation on a port-in order. FOC (portDate) must be
        today or earlier, and the numbers must be in routing on the Sinch
        network.
      summary: List port-in activation groups
      parameters:
        - in: path
          name: orderId
          schema:
            type: string
          example: 897867
          required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    phoneNumberGroup:
                      type: string
                      example: GW Verizon Grp1
                    focDate:
                      type: string
                    phoneNumbers:
                      type: array
                      items:
                        type: object
                        properties:
                          phoneNumber:
                            type: string
                          voiceConfiguration:
                            $ref: '#/components/schemas/VoiceConfiguration'
                          smsConfiguration:
                            $ref: '#/components/schemas/SmsConfiguration'
  /orders/portIns/{orderId}/activate:
    post:
      tags:
        - Advanced porting
      operationId: activatePortIn
      summary: On demand activation
      description: >-
        Activate numbers that are ready to be ported.

        Confirmation date (FOC) must be today or earlier,

        and the numbers must be in routing on the Sinch network (occurs at
        midnight on the date of the port, after concurrence,

        or following the 18-hour wireline port timer expiration on expedited
        ports).


        **Note:** In order to send SMS and MMS messages in the US using 10DLC
        phone numbers, all messages must be sent via an approved campaign. Your
        campaigns are managed under US 10DLC Campaigns in the SMS section. A
        number can be associated to an approved campaign after the port
        completes.
      parameters:
        - in: path
          name: orderId
          schema:
            type: string
          example: 897867
          required: true
      requestBody:
        $ref: '#/components/requestBodies/ActivatePortInRequest'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortInOrderGroup'
  /orders/portIns/{orderId}:
    get:
      tags:
        - Port-in numbers
      operationId: getOrderDetails
      summary: Get  order Detail
      description: >-
        Get details about an existing order along with order notes and process
        notes (for Port-In orders).

        For realtime updates on the order status, please refer to the Webhooks
        section. wich is the recommended way to get updates on the order status.
      parameters:
        - in: path
          name: orderId
          schema:
            type: number
          required: true
          description: Order Identifier
          example: 897867
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderBaseItem'
    delete:
      tags:
        - Port-in numbers
      operationId: deleteOrder
      summary: Cancel Pending Order
      description: This operation allows you to cancel an order in Pending status.
      parameters:
        - in: path
          name: orderId
          schema:
            type: number
          required: true
          description: Order Identifier
          example: 897867
      responses:
        '200':
          description: Successful operation
    put:
      operationId: updatePortInOrder
      tags:
        - Port-in numbers
      summary: Update port-in order
      description: >-
        This operation allows you to update information on a Pending order.
        Please note that you need to send the full object, its not a patch
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier for the order.
      requestBody:
        required: true
        description: Update Pending Order
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderBaseItem'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderBaseItem'
  /orders/portIns/{orderId}/notes:
    post:
      tags:
        - Port-in numbers
      operationId: addOrderNote
      summary: Add Order Note
      description: This operation allows you to add a note to an existing order.
      parameters:
        - in: path
          name: orderId
          schema:
            type: number
          required: true
          description: Order Identifier
      requestBody:
        required: true
        description: Add Order Note
        content:
          application/json:
            schema:
              type: object
              properties:
                note:
                  type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: number
                  note:
                    type: string
  /orders/portIns/{orderId}/documents:
    post:
      operationId: addOrderDocuments
      tags:
        - Port-in numbers
      summary: Add Order Document
      description: This operation allows you to add a document to an existing order.
      parameters:
        - in: path
          name: orderId
          schema:
            type: number
          required: true
          description: Order Identifier
      requestBody:
        required: true
        description: Add Order Document
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderDocumentWithContent'
      responses:
        '200':
          description: >-
            Successful operation, the file name/description would be returned,
            but the content would not be returned in the response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDocumentBase'
  /orders/{orderId}/documents/{documentId}:
    get:
      operationId: getOrderDocumentContent
      tags:
        - Port-in numbers
      summary: Get document content
      description: >-
        This operation allows you to retrieve specific document contents
        attached to an existing order.
      parameters:
        - in: path
          name: orderId
          schema:
            type: number
          required: true
          description: Order Identifier
        - in: path
          name: documentId
          description: Document content for
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      documentId:
                        type: number
                  - $ref: '#/components/schemas/OrderDocumentWithContent'
                  - type: object
                    properties:
                      contentType:
                        type: string
webhooks:
  OrderUpdated:
    post:
      operationId: order
      summary: Order Updated
      description: >-
        This is a webhook that will be called when an order is updated, it will
        contain the order and the status of the order.
      tags:
        - Webhooks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderWebhookStatusEvent'
            example:
              type: ORDER_UPDATED
              orderId: '897867'
              order:
                id: 897867
                customerOrderReference: '123456'
                desiredPortSchedule:
                  desiredPortDate: '2024-09-24'
                  desiredPortTime: 09:00:00Z
                status: PENDING
                onDemandActivation: false
                phoneNumbers:
                  - phoneNumber: '+12345678901'
                    portOutInfo:
                      existingPortOutPin: '1234'
                    endUser:
                      name: John Doe
                      streetName: Main St
                      streetNum: '123'
                      city: Anytown
                      state: NY
                      zipCode: '12345'
                    voiceConfiguration:
                      type: EST
                      trunkId: '123456'
  NumbersActivated:
    post:
      operationId: numbersActivated
      summary: Number activated
      description: >-
        This notification occurs if at least one number on the port order was
        activated.
      tags:
        - Webhooks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NumberStatusWebhookStatusEvent'
            example:
              type: NUMBERS_ACTIVATED
              orderId: 897867
              phoneNumbers:
                - phoneNumber: '+12345678901'
                  status: Activated
                  activatedDate: '2024-09-24T12:00:00Z'
  NumbersConfirmed:
    post:
      operationId: NumbersConfirmed
      summary: Number confirmed
      description: >-
        This notification occurs when at least one number on the port order was
        confirmed. This notification also occurs when the number is ready to be
        activated and `onDemandActivation` was set to true or if it will be
        activated at the specified confirmation date.
      tags:
        - Webhooks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NumberStatusWebhookStatusEvent'
            example:
              type: NUMBERS_CONFIRMED
              orderId: 897867
              phoneNumbers:
                - phoneNumber: '+12345678901'
                  status: Confirmed
                  confirmedDate: '2024-09-24T12:00:00Z'
  NumbersRejected:
    post:
      operationId: NumbersRejected
      summary: Number Rejected
      description: >-
        This notification occurs if at least one number on the port order was
        rejected. Look at rejected reasons for more details on what went wrong.
      tags:
        - Webhooks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NumberStatusWebhookStatusEvent'
            example:
              type: NUMBERS_REJECTED
              orderId: 897867
              phoneNumbers:
                - phoneNumber: '+12345678901'
                  status: Confirmed
                  confirmedDate: '2024-09-24T12:00:00Z'
  NewOrderNote:
    post:
      operationId: NewOrderNote
      summary: Note added to order
      description: >-
        This notification occurs if a note was added to the order either by
        Sinch or by you.
      tags:
        - Webhooks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewNoteWebhookStatusEvent'
            example:
              type: NEW_ORDER_NOTE
              orderId: 897867
              note: This is a note
components:
  parameters:
    Page:
      in: query
      name: page
      description: >-
        The page you want to retrieve returned from a previous List request, if
        any
      schema:
        type: string
    PageSize:
      name: pageSize
      in: query
      description: >-
        The maximum number of items to return per request. The default is 100
        and the maximum is 1000. If you need to export larger amounts and
        pagination is not suitable for you can use the Export function in the
        dashboard.
      schema:
        type: integer
        maximum: 1000
        minimum: 1
  requestBodies:
    OrderPortInRequest:
      content:
        application/json:
          schema:
            required:
              - desiredPortSchedule
              - phoneNumbers
            allOf:
              - $ref: '#/components/schemas/OrderBaseItem'
          example:
            desiredPortSchedule:
              desiredPortDate: '2025-01-31'
              desiredPortTime: '10:00:00'
              desiredPortTimeZone: US/Eastern
            phoneNumbers:
              - phoneNumber: '+12345678901'
                voiceConfiguration:
                  type: EST
                  trunkId: '123456'
                portOutInfo:
                  existingPortOutPin: '1234'
                endUser:
                  name: John Doe
                  streetName: Main St
                  streetNum: '123'
                  city: Anytown
                  state: NY
                  zipCode: '12345'
    ActivatePortInRequest:
      required: false
      description: >-
        If you want to only activate certain numbers in the order, include this
        request body with the phone numbers you want to activate.
      content:
        application/json:
          schema:
            type: object
            properties:
              phoneNumberGroups:
                type: array
                items:
                  type: string
                  description: The phone number in the order you want to port-in.
                  example: '+17775559999'
  schemas:
    Pagination:
      type: object
      description: An object describing how pages of items are displayed.
      readOnly: true
      properties:
        page:
          readOnly: true
          type: integer
          description: Current page.
        totalPages:
          readOnly: true
          type: integer
          description: Total number of pages.
        pageSize:
          readOnly: true
          type: integer
          description: Number of items per page.
        totalItems:
          type: integer
          readOnly: true
          format: int32
          description: Total size of the result.
    WebhookEvent:
      type: object
      description: A webhook event.
      properties:
        event:
          type: string
          description: The event that triggered the webhook.
          enum:
            - ORDER_UPDATED
            - NUMBERS_ACTIVATED
            - NUMBERS_CONFIRMED
            - NUMBERS_REJECTED
            - NEW_ORDER_NOTE
          x-enumDescriptions:
            ORDER_UPDATED: >-
              The order was updated. This could be a status update or any other
              updates to a pending order.
            NUMBERS_ACTIVATED: At least one number was activated.
            NUMBERS_CONFIRMED: At least one number was confirmed.
            NUMBERS_REJECTED: At least one number was rejected.
            NEW_ORDER_NOTE: A new note was added to the order.
        orderId:
          type: string
          description: The order ID that was updated.
    OrderWebhookStatusEvent:
      allOf:
        - $ref: '#/components/schemas/WebhookEvent'
        - type: object
          properties:
            event:
              type: string
              description: The event that triggered the webhook
              enum:
                - ORDER_UPDATED
              default: ORDER_UPDATED
              x-enumDescriptions:
                ORDER_UPDATED: >-
                  The order was updated it can be status or any other updates to
                  a pending order
            order:
              $ref: '#/components/schemas/OrderBaseItem'
    NumberStatusWebhookStatusEvent:
      allOf:
        - $ref: '#/components/schemas/WebhookEvent'
        - type: object
          properties:
            event:
              type: string
              description: The event that triggered the webhook
              enum:
                - NUMBERS_ACTIVATED
                - NUMBERS_CONFIRMED
                - NUMBERS_REJECTED
              default: NUMBERS_ACTIVATED
            phoneNumbers:
              type: array
              items:
                $ref: '#/components/schemas/PhoneNumberMinItem'
    NewNoteWebhookStatusEvent:
      allOf:
        - $ref: '#/components/schemas/WebhookEvent'
        - type: object
          properties:
            note:
              type: string
              description: The note that was added.
    PortInOrderGroup:
      type: object
      description: The collection of port-in orders.
      properties:
        phoneNumberGroups:
          type: array
          description: A group of phone numbers to be ported in.
          items:
            type: object
            properties:
              phoneNumberGroup:
                type: string
              status:
                type: string
    OrderStatus:
      type: string
      description: The current status of the port order.
      enum:
        - PENDING
        - CONFIRMED
        - COMPLETED
        - PENDING_CANCELATION
        - CANCELED
      readOnly: true
      x-enumDescriptions:
        ORDER_BUILDING: The order is being created
        PENDING: The order is pending, and can be updated
        CONFIRMED: >-
          The order is confirmed, and can not be updated but if onDemand is true
          it can be activated
        COMPLETED: >-
          The order is completed, the port has completed and the numbers are
          active
        PENDING_CANCELATION: >-
          The order is in the process of being cancelled. During this time you
          cannot submit the same numbers on a new order
        CANCELED: The order is cancelled, either by the customer or by the system
    DefaultsConfiguration:
      type: object
      description: >-
        Default configuration properties. If you do not provide values when
        making requests these values will be used instead.
      properties:
        contact:
          type: object
          description: Contains the contact information for the default user.
          properties:
            email:
              type: string
              description: The email address of the default user.
              example: name@email.com
            name:
              type: string
              description: The name of the default user.
              example: John Smith
            phone:
              type: string
              description: The phone number of the default user.
              example: '+15559999'
        webhookUrl:
          type: string
          description: The default webhook URL to use for callbacks.
          example: my.callback.server
        defaultPortTime:
          type: string
          description: >-
            The default time for porting in numbers. If you don't specify a time
            in the order this time will be used.
          example: '09:00:00'
        defaultPortTimeZone:
          type: string
          enum:
            - US/Eastern
            - US/Central
            - US/Mountain
            - US/Pacific
          x-enumDescriptions:
            US/Eastern: US Eastern Timezone
            US/Central: US Central Timezone
            US/Mountain: US Mountain Timezone
            US/Pacific: US Pacific Timezone
          description: >-
            The default time zone for porting in numbers. If you don't specify a
            time zone in the order, this time zone will be used.
    DesiredPortDateTime:
      required:
        - desiredPortDate
      type: object
      properties:
        desiredPortDate:
          type: string
          description: The date you want the numbers to be ported in, in ISO format.
          example: '2025-01-31'
        desiredPortTime:
          type: string
          example: '09:00:00'
          description: The time you want the numbers to be ported in.
        desiredPortTimeZone:
          type: string
          enum:
            - US/Eastern
            - US/Central
            - US/Mountain
            - US/Pacific
          x-enumDescriptions:
            US/Eastern: US Eastern Timezone
            US/Central: US Central Timezone
            US/Mountain: US Mountain Timezone
            US/Pacific: US Pacific Timezone
          description: The time zone you want to use for the desired port time.
          example: US/Eastern
    OrderBaseItem:
      type: object
      required:
        - desiredPortSchedule
      properties:
        id:
          type: number
          description: The unique identifier for the order
          readOnly: true
          example: 890192331
        status:
          $ref: '#/components/schemas/OrderStatus'
        customerOrderReference:
          type: string
          description: Your reference you specified when creating the order
          example: '123456'
          default: ''
        onDemandActivation:
          type: boolean
          description: >-
            If you use onDemand activation you will need to make sure the
            numbers are both confirmed and released for activation, if you don't
            use onDemand the numbers will be activated on the desiredPortDate is
            the recommended way.

            If true the numbers will be activated as when you call `:activate`,
            if false they will be activated on the desiredPortDate
          default: false
        desiredPortSchedule:
          description: >-
            The date and time you want the numbers to be ported in. If you set a
            `defaultPortTime` and `defaultPortTimeZone` in defaults those
            settings will be used if not set per order. If you haven't set
            defaults and do not set the time and time zone on the order the
            system default will be used.


            **System Default Time:** 09:00:00 US/Eastern
          $ref: '#/components/schemas/DesiredPortDateTime'
        loaUploadedBy:
          type: string
          description: Name of the user uploading the LOA
          example: john doe
        loaAttachmentDate:
          description: >-
            Date when the LOA was uploaded. Formatted as
            [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601):
            `YYYY-MM-DDThh:mm:ss.SSSZ`.
          type: string
          format: date-time
          example: '2024-09-24T12:00:00Z'
        phoneNumbers:
          type: array
          title: Phone numbers
          description: The numbers for the order in e164 format
          items:
            $ref: '#/components/schemas/PhoneNumberMinItem'
        notes:
          readOnly: true
          description: >-
            Notes if any on the order, you will get notes if there is any
            problems with the order and you send notes as reply to those
            problems
          type: array
          items:
            $ref: '#/components/schemas/OrderNote'
        documents:
          readOnly: true
          description: >-
            Documents if any on the order, you will get documents if there is
            any problems with the order and you send documents as reply to those
            problems
          type: array
          items:
            $ref: '#/components/schemas/OrderDocumentBase'
        createdDate:
          readOnly: true
          description: >-
            When the order was created. Formatted as
            [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601):
            `YYYY-MM-DDThh:mm:ss.SSSZ`.
          type: string
          format: date-time
          example: '2024-09-24T12:00:00Z'
        resellerName:
          type: string
          description: >-
            **This is requirement for canadian numbers only, we need to figure
            out what we expect here and where the customer can find this info**
          default: ''
    PhoneNumberGroupItem:
      type: object
      description: >-
        We group phone numbers by carrier so you can see the status of the
        numbers by carrier
      properties:
        phoneNumberGroup:
          type: string
        focDate:
          type: string
        phoneNumbers:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/PhoneNumberItem'
    OrderListItem:
      type: object
      properties:
        id:
          type: number
          description: The unique identifier for the order
          readOnly: true
          example: 890192331
        status:
          $ref: '#/components/schemas/OrderStatus'
        customerOrderReference:
          type: string
          description: Your reference you specified when creating the order
          example: '123456'
          default: ''
        createdDate:
          readOnly: true
          description: >-
            When the order was created. Formatted as
            [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601):
            `YYYY-MM-DDThh:mm:ss.SSSZ`.
          type: string
          format: date-time
          example: '2024-09-24T12:00:00Z'
        phoneNumberQuantity:
          type: number
          readOnly: true
          description: >-
            The number of phone numbers in the order, a helper property for you,
            this can also be done by and counting on the `numbers` collection
        focQuantity:
          type: number
          readOnly: true
          description: >-
            The number of phone numbers that are confirmed, a helper property
            for you, this can also be done by and counting on the `numbers`
            collection and  filtering on status `CONFIRMED`
        activatedQuantity:
          type: number
          readOnly: true
          description: >-
            The number of phone numbers that are activated, The number of phone
            numbers that are confirmed, a helper property for you, this can also
            be done by and counting on the `numbers` collection and  filtering
            on status `COMPLETE`
        rejectedQuantity:
          type: number
          readOnly: true
          description: >-
            The number of phone numbers that are rejected, This can be done by
            counting on the `phoneNumbers` collection and  filtering on status
            `REJECTED`
        excludedQuantity:
          type: number
          readOnly: true
          description: >-
            The number of phone numbers that are activated, The number of phone
            numbers that are confirmed, a helper property for you, this can also
            be done by and counting on the `numbers` collection and filtering on
            status `EXCLUDED`
    PortOutItem:
      type: object
      description: >-
        The port out information at the previous carrier for the number. Usually
        only a port-out PIN is required.
      properties:
        existingPortOutPin:
          type: string
          description: The existing port-out PIN from the previous carrier.
        accountNum:
          type: string
          description: >-
            The account number associated with the number from the previous
            carrier.
        accountPhoneNumber:
          type: string
          description: The contact phone number on the account.
        authorizingName:
          type: string
          description: Name of the person authorizing the port-in.
        authorizingDate:
          type: string
          description: >-
            Date of authorizing the port-in (must be today or earlier and cannot
            be in the future). Formatted as
            [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601):
            `YYYY-MM-DDThh:mm:ss.SSSZ`.
          format: date-time
          example: '2024-09-24T12:00:00Z'
    PhoneNumberMinItem:
      type: object
      description: The minimum required fields for a phone number to be ported.
      required:
        - phoneNumber
        - endUser
      allOf:
        - $ref: '#/components/schemas/PhoneNumberItem'
    PhoneNumberItem:
      type: object
      required:
        - phoneNumber
        - endUser
        - portOutInfo
      properties:
        phoneNumber:
          type: string
          description: >-
            The phone number in
            [E.164](https://community.sinch.com/t5/Glossary/E-164/ta-p/7537)
            format.
          format: e164
          example: '+12345678901'
        status:
          type: string
          description: The porting status of the phone number.
          default: PENDING
          readOnly: true
          enum:
            - PENDING
            - CONFIRMED
            - REJECTED
            - ACTIVATED
            - CANCELED
            - EXCLUDED
          x-enumDescriptions:
            PENDING: The number is pending, and can be updated.
            CONFIRMED: >-
              The number is confirmed, and can not be updated but if onDemand is
              true it can be activated.
            REJECTED: >-
              The number is rejected. Look at the rejectReason for more details.
              Reasons can be either its not portable or wrong port out
              information.
            ACTIVATED: The number is activated.
            CANCELED: The number is cancelled, either by the customer or by the system.
            EXCLUDED: >-
              The number is excluded from the order. Look at the exclusionReason
              for more details.
        exclusionReason:
          description: >-
            If the phone number is excluded or rejected, the status here would
            reflect as such. In this case, there would be an exclusion reason
            along with date of exclusion.
          type: string
          readOnly: true
          default: ''
        exclusionTime:
          description: >-
            If the phone number is excluded or rejected, this is the date and
            time it was excluded. This is accompanied by the `exclusionReason`.
            Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601):
            `YYYY-MM-DDThh:mm:ss.SSSZ`.
          type: string
          readOnly: true
          format: date-time
          example: '2024-09-24T12:00:00Z'
        countryCode:
          description: >-
            The ISO 3166-1 formatted country code of the phone number, for
            example, US or CA. At the moment, only North American numbers are
            supported.
          type: string
          readOnly: true
          example: US
        activateTime:
          description: The time the number was activated in the UTC timezone.
          type: string
          readOnly: true
          example: '14:00'
        activateUser:
          readOnly: true
          description: The user that activated the number.
          type: string
        voiceConfiguration:
          description: >-
            If specified, this will override the voice configuration for the
            order.
          $ref: '#/components/schemas/VoiceConfiguration'
        smsConfiguration:
          description: >-
            If specified, this will override the sms configuration for the
            order.
          $ref: '#/components/schemas/SmsConfiguration'
        endUser:
          description: If specified, this will override the endUser for the order.
          $ref: '#/components/schemas/EndUser'
        portOutInfo:
          $ref: '#/components/schemas/PortOutItem'
        features:
          $ref: '#/components/schemas/Feature'
        newPortOutPin:
          type: string
        rejectReason:
          readOnly: true
          type: string
          description: The reason the number was rejected.
        excludedFeatures:
          readOnly: true
          description: Features that are excluded for the phone number being ported.
          type: array
          items:
            type: object
            properties:
              featureName:
                description: The name of the excluded feature.
                type: string
              exclusionReason:
                description: The reason the feature was excluded.
                type: string
        phoneNumberGroup:
          readOnly: true
          type: string
          example: GW Verizon Grp1
        focDate:
          description: >-
            Once the phone number has a firm order confirmation (FOC) date, it
            will be returned as part of the phone number details. Formatted as
            [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601):
            `YYYY-MM-DDThh:mm:ss.SSSZ`.
          readOnly: true
          type: string
          format: date-time
          example: '2024-09-24T12:00:00Z'
    OrderNote:
      type: object
      properties:
        note:
          type: string
          description: The message of the note.
        createdTime:
          type: string
          description: >-
            The date and time when the note was created in UTC ISO
            https://www.ietf.org/rfc/rfc3339.txt.
        createdBy:
          type: string
          description: The user who created the note.
    OrderDocumentBase:
      type: object
      description: Response object containing information about the order document.
      properties:
        id:
          type: number
          readOnly: true
          description: The ID of the order document.
        documentName:
          type: string
          description: The name of the document.
        description:
          type: string
          description: A description of the contents of the document.
    OrderDocumentWithContent:
      type: object
      allOf:
        - $ref: '#/components/schemas/OrderDocumentBase'
        - type: object
          properties:
            fileContent:
              type: string
              description: Base64-encoded content representing the file contents.
    SmsConfiguration:
      type: object
      description: >-
        Configuration for what sms service id to use, and other sms related
        configurations
      properties:
        smsAppId:
          type: string
    RTCConfiguration:
      type: object
      title: RTC
      description: If you want to use the number with programmable voice
      properties:
        type:
          type: string
          enum:
            - RTC
          x-enumDescriptions:
            RTC: Indicates programmable voice capability.
          default: RTC
        appId:
          type: string
          description: The app id from the dashboard where you want to use the number
          example: 6afd2da3-1692-4443-834c-8a2f386ec284
    ESTConfiguration:
      type: object
      title: EST
      description: When you want to use the number for elastic sip trunking
      properties:
        type:
          type: string
          enum:
            - EST
          x-enumDescriptions:
            EST: Indicates Elastic SIP Trunking capability.
          default: EST
        trunkId:
          type: string
          example: 01G65Z755AFWAKHE12NY0CQ9FH
    FAXConfiguration:
      type: object
      title: FAX
      description: When you want to use the number for fax
      properties:
        type:
          type: string
          enum:
            - FAX
          x-enumDescriptions:
            FAX: Indicates Fax capability.
          default: FAX
        serviceId:
          type: string
          example: 01G65Z755GHWAKHE12NY0CQO0T
    VoiceConfiguration:
      description: Configuration for voice
      discriminator:
        propertyName: type
        mapping:
          RTC: '#/components/schemas/RTCConfiguration'
          EST: '#/components/schemas/ESTConfiguration'
          FAX: '#/components/schemas/FAXConfiguration'
      oneOf:
        - $ref: '#/components/schemas/RTCConfiguration'
        - $ref: '#/components/schemas/ESTConfiguration'
        - $ref: '#/components/schemas/FAXConfiguration'
    Feature:
      type: object
      properties:
        e911:
          type: object
          description: >-
            An object describing the emergency 911 contact address associated
            with the number.
          properties:
            name:
              type: string
              description: The contact name.
            streetNum:
              type: string
              description: The street number for the emergency address.
              example: '12345'
            streetInfo:
              type: string
              description: The street name of the emergency location.
              example: Main St
            location:
              type: string
              description: The location for address.
              example: Apt 5
            city:
              type: string
              description: The city of the emergency location.
              example: Springfield
            state:
              type: string
              description: The state or province of the emergency location.
              example: IL
            postalCode:
              type: string
              description: The postal code of the emergency location.
              example: '62701'
            postalCodePlusFour:
              type: string
              description: The postal code of the emergency location.
              example: '1234'
            enhStreetNum:
              description: The validated street number.
              type: string
              readOnly: true
            enhStreetInfo:
              description: The validated street.
              type: string
              readOnly: true
            enhLocation:
              description: The validated street location.
              type: string
              readOnly: true
            enhCity:
              description: The validated city.
              type: string
              readOnly: true
            enhState:
              description: The validated state.
              type: string
              readOnly: true
            enhPostalCode:
              description: The validated postal code.
              type: string
              readOnly: true
            enhPostalCodePlusFour:
              description: The validated postal code +4 digits.
              type: string
              readOnly: true
    EndUser:
      type: object
      required:
        - name
        - streetNum
        - streetName
        - city
        - state
        - zipCode
      properties:
        name:
          type: string
          description: >-
            The name of the end user can be a person's name or company name.
            Please note if you are not using this yourself it should be the
            name/company of the actual user.
          example: Joe Doe
        streetNum:
          description: The end user's street number.
          type: string
          example: '123'
        streetName:
          description: The end user's street name.
          type: string
          example: Main
        streetPreDir:
          description: The prefix direction in the end user's address, if any.
          type: string
          default: ''
          example: 'N'
        streetType:
          description: The end user's street type, for example Road or Court.
          type: string
          default: ''
          example: Court
        streetPostDir:
          description: The suffix direction in the end user's address, if any.
          type: string
          default: ''
          example: SW
        locationType1:
          type: string
          description: Any additional location information, such as suite or apartment.
          example: Suite
        locationValue1:
          description: >-
            Any additional location information, such as suite number or
            apartment number.
          type: string
          example: '2134'
        locationType2:
          description: >-
            Field for additional location information, such as suite number or
            apartment number.
          type: string
          example: ''
          default: ''
        locationValue2:
          description: >-
            Field for additional location information, such as suite number or
            apartment number.
          type: string
          example: ''
          default: ''
        locationType3:
          description: >-
            Field for additional location information, such as suite number or
            apartment number.
          type: string
          example: ''
          default: ''
        locationValue3:
          description: >-
            Field for additional location information, such as suite number or
            apartment number.
          type: string
          example: ''
          default: ''
        city:
          description: The end user's city.
          type: string
          example: Anytown
        state:
          type: string
          description: The end user's state, using the two letter abbreviation.
          example: CA
        zipCode:
          description: The end user's zip code.
          type: string
          example: '12345'
          default: ''
        typeOfService:
          type: string
          description: >-
            The type of address. Available values are `B` for Business or `R`
            for Residence
          enum:
            - B
            - R
          x-enumDescriptions:
            B: Business
            R: Residence
          example: B
          default: B
    PortabilityCheckRequest:
      type: object
      description: The request body for the checkPortability endpoint.
      properties:
        phoneNumbers:
          type: array
          items:
            type: string
            description: A phone number in E.164 format.
            example: '+12311234567'
    PortabilityCheckResponse:
      type: object
      description: The response body for the checkPortability endpoint.
      properties:
        phoneNumbers:
          type: array
          items:
            $ref: '#/components/schemas/PortabilityCheckNumber'
    PortabilityCheckNumber:
      type: object
      description: >-
        An object containing information about whether a phone number can be
        ported or not.
      properties:
        phoneNumber:
          type: string
          description: A phone number in E.164 format.
          example: '+12345678901'
        portable:
          type: boolean
          description: Indicates if a number is portable or not.
          example: true
        carrier:
          type: string
          description: The carrier to which the number belongs.
          example: T-Mobile
        reason:
          type: string
          description: If applicable, the reason why the number cannot be ported.
          example: ''
    Error:
      type: object
      properties:
        code:
          description: HTTP status code or error code
          readOnly: true
          type: integer
          format: int32
          example: 400
        status:
          description: Response status name.
          readOnly: true
          type: string
          example: INVALID_ARGUMENT
        message:
          type: string
          readOnly: true
          description: A developer-facing error message
          example: Bad request.
        details:
          readOnly: true
          description: Details of the errors
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
    ErrorDetail:
      type: object
      anyOf:
        - $ref: '#/components/schemas/NotFoundDetail'
        - $ref: '#/components/schemas/BadRequestDetail'
        - $ref: '#/components/schemas/ErrorInfo'
      discriminator:
        propertyName: type
        mapping:
          NotFound: '#/components/schemas/NotFoundDetail'
          BadRequest: '#/components/schemas/BadRequestDetail'
          ErrorInfo: '#/components/schemas/ErrorInfo'
    NotFoundDetail:
      type: object
      description: The request was malformed on one or more fields.
      x-internal: >-
        https://github.com/googleapis/googleapis/blob/f79d6e85a9a6b913a5e9cb0067e846e7f087dbc8/google/rpc/error_details.proto#L169
      properties:
        type:
          type: string
          description: The request was malformed on one or more properties.
          readOnly: true
          example: NOT_FOUND
          default: BadRequest
    ErrorInfo:
      description: Describes the cause of the error with structured details.
      type: object
      properties:
        type:
          type: string
          description: The type of error.
          default: ErrorInfo
          example: ErrorInfo
        reason:
          type: string
          description: >-
            The reason of the error. This is a constant value that identifies
            the proximate cause of the error. Error reasons are unique. Max 63
            characters and match /[A-Z0-9_]+/.
          maxLength: 63
          example: DESTINATION_BLOCKED
        domain:
          type: string
          description: Domain for error, for voice it is always `sinch.voice`.
          example: VOICE
        metaData:
          description: >-
            Additional structured details about this error. key value pair of
            strings
          type: object
          example:
            country: Bermuda
    BadRequestDetail:
      type: object
      description: The request was malformed on one or more fields.
      x-internal: >-
        https://github.com/googleapis/googleapis/blob/f79d6e85a9a6b913a5e9cb0067e846e7f087dbc8/google/rpc/error_details.proto#L169
      properties:
        type:
          type: string
          description: The request was malformed on one or more properties.
          readOnly: true
          example: BadRequest
          default: BadRequest
        fieldViolations:
          description: The field violation(s).
          type: array
          items:
            $ref: '#/components/schemas/FieldViolation'
          example:
            - field: to
              description: Phone number was not in the expected format.
    FieldViolation:
      type: object
      properties:
        field:
          type: string
          readOnly: true
          description: Request field.
          example: to
        description:
          type: string
          readOnly: true
          description: Description of why the request field was considered invalid.
          example: Phone number was not in the expected format.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Your key ID and Key secret serve as the username and password,
        respectively. Both can be found in the [Sinch Build
        Dashboard](https://dashboard.sinch.com/settings/access-keys). For more
        information about basic authentication in the Numbers API, click
        [here](https://developers.sinch.com/docs/numbers/api-reference/authentication/basic).
    bearerAuth:
      type: oauth2
      description: >-
        The username and password are your Key ID and Key Secret from the [Sinch
        Build Dashboard](https://dashboard.sinch.com/settings/access-keys).
        Exchange these for a bearer token (access token). Learn how
        [here](https://developers.sinch.com/docs/numbers/api-reference/authentication/oauth).
      flows:
        clientCredentials:
          tokenUrl: https://auth.sinch.com/oauth2/token
          scopes: {}
