surge_api 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e4a0bcd739442f5fcd6b9ca030978f0da11f700af746fac3675be506613fea9
-  data.tar.gz: c87b52cbe1bc4ebf481ba325bf303df5789b149eb4b8873d9a4d5f526416db69
+  metadata.gz: 2c7a5d469cecb86e54c11530c7f97365e055e1990f7689c060a574cb7a7db892
+  data.tar.gz: 9b8688276c1c6de57242aa3ea37846db616c6dd9fb9d0cb89928d17ff9faa816
 SHA512:
-  metadata.gz: c8c6a4eae6015cdcc0e950d1f629194ea88d7df136c469c5859c49a5c65a47e05cecca62d6ac9c6f42f2d1f35cd9a067d6ae9bb9ed2617f95b49786334597338
-  data.tar.gz: 4f82ac61c2cf4a14780d9796fbf67ad90b503ff14ff429eb42b8ac8a652cd6b06ff7ec8cffe244e9c3591f314e9bbff7b9e1c3f142cfff81d045b82bd3f7393b
+  metadata.gz: 7ac007b01940925b65714cd5f48c76ba82ff502450e316a971ba89bc578bd18deef2135ebf95c2a6c4f617688ad77f29d92ce149ab85ca57acf25a80de6f26ed
+  data.tar.gz: 95caca6f433199cdea6a8f1ef3ace3d87d1a431e8bb3f12e2d99b788951d9bed9dfd934e9463b21c4d8d2da0c1fdc382db8cbb2abadc801ef9a13ad0d4d50efa

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.20.0 (2026-07-14)
+
+Full Changelog: [v0.19.0...v0.20.0](https://github.com/surgeapi/ruby-sdk/compare/v0.19.0...v0.20.0)
+
+### Features
+
+* **api:** add campaign to phone numbers ([037405d](https://github.com/surgeapi/ruby-sdk/commit/037405d891eaa84c91ede8b963d91a1910b1379e))
+* **api:** add list available phone numbers endpoint ([d54f29f](https://github.com/surgeapi/ruby-sdk/commit/d54f29f90abc8cdc9d42577775bdbe727898d19f))
+* **api:** add phone number field to purchase endpoint ([d9eafc6](https://github.com/surgeapi/ruby-sdk/commit/d9eafc611da5fb60b149eda5a676d3ca276b3780))
+* **api:** add retrieve phone number endpoint ([2f15b40](https://github.com/surgeapi/ruby-sdk/commit/2f15b4093fd0ed099e41c2292ca9a433458eec19))
+
 ## 0.19.0 (2026-07-06)
 
 Full Changelog: [v0.18.0...v0.19.0](https://github.com/surgeapi/ruby-sdk/compare/v0.18.0...v0.19.0)

data/README.md

@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "surge_api", "~> 0.19.0"
+gem "surge_api", "~> 0.20.0"
 ```
 
 <!-- x-release-please-end -->
@@ -261,23 +261,23 @@ Since this library does not depend on `sorbet-runtime`, it cannot provide [`T::E
 
 ```ruby
 # :local
-puts(SurgeAPI::PhoneNumberPurchaseParams::Type::LOCAL)
+puts(SurgeAPI::PhoneNumberListAvailableNumbersParams::Type::LOCAL)
 
-# Revealed type: `T.all(SurgeAPI::PhoneNumberPurchaseParams::Type, Symbol)`
-T.reveal_type(SurgeAPI::PhoneNumberPurchaseParams::Type::LOCAL)
+# Revealed type: `T.all(SurgeAPI::PhoneNumberListAvailableNumbersParams::Type, Symbol)`
+T.reveal_type(SurgeAPI::PhoneNumberListAvailableNumbersParams::Type::LOCAL)
 ```
 
 Enum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:
 
 ```ruby
 # Using the enum constants preserves the tagged type information:
-surge.phone_numbers.purchase(
-  type: SurgeAPI::PhoneNumberPurchaseParams::Type::LOCAL,
+surge.phone_numbers.list_available_numbers(
+  type: SurgeAPI::PhoneNumberListAvailableNumbersParams::Type::LOCAL,
   # …
 )
 
 # Literal values are also permissible:
-surge.phone_numbers.purchase(
+surge.phone_numbers.list_available_numbers(
   type: :local,
   # …
 )

data/lib/surge_api/models/phone_number.rb

@@ -2,7 +2,7 @@
 
 module SurgeAPI
   module Models
-    # @see SurgeAPI::Resources::PhoneNumbers#update
+    # @see SurgeAPI::Resources::PhoneNumbers#retrieve
     class PhoneNumber < SurgeAPI::Internal::Type::BaseModel
       # @!attribute id
       #   Unique identifier for the phone number
@@ -10,8 +10,17 @@ module SurgeAPI
       #   @return [String]
       required :id, String
 
+      # @!attribute campaign
+      #   Campaign attachment details for a domestic local phone number
+      #
+      #   @return [SurgeAPI::Models::PhoneNumber::Campaign, nil]
+      required :campaign, -> { SurgeAPI::PhoneNumber::Campaign }, nil?: true
+
       # @!attribute campaign_id
-      #   The unique identifier of the campaign this phone number is attached to, if any
+      #   @deprecated Use `campaign.id` instead.
+      #
+      #   Deprecated. The unique identifier of the campaign this phone number is attached
+      #   to, if any
       #
       #   @return [String, nil]
       required :campaign_id, String, nil?: true
@@ -34,12 +43,17 @@ module SurgeAPI
       #   @return [Symbol, SurgeAPI::Models::PhoneNumber::Type]
       required :type, enum: -> { SurgeAPI::PhoneNumber::Type }
 
-      # @!method initialize(id:, campaign_id:, name:, number:, type:)
+      # @!method initialize(id:, campaign:, campaign_id:, name:, number:, type:)
+      #   Some parameter documentations has been truncated, see
+      #   {SurgeAPI::Models::PhoneNumber} for more details.
+      #
       #   A phone number that can be used to send and receive messages and calls
       #
       #   @param id [String] Unique identifier for the phone number
       #
-      #   @param campaign_id [String, nil] The unique identifier of the campaign this phone number is attached to, if any
+      #   @param campaign [SurgeAPI::Models::PhoneNumber::Campaign, nil] Campaign attachment details for a domestic local phone number
+      #
+      #   @param campaign_id [String, nil] Deprecated. The unique identifier of the campaign this phone number is attached
       #
       #   @param name [String, nil] A human-readable name for the phone number
       #
@@ -47,6 +61,43 @@ module SurgeAPI
       #
       #   @param type [Symbol, SurgeAPI::Models::PhoneNumber::Type] Whether the phone number is local, toll-free, or short code
 
+      # @see SurgeAPI::Models::PhoneNumber#campaign
+      class Campaign < SurgeAPI::Internal::Type::BaseModel
+        # @!attribute id
+        #   The unique identifier of the campaign this phone number is attached to
+        #
+        #   @return [String]
+        required :id, String
+
+        # @!attribute attachment_status
+        #   The current campaign attachment status for this phone number.
+        #
+        #   @return [Symbol, SurgeAPI::Models::PhoneNumber::Campaign::AttachmentStatus]
+        required :attachment_status, enum: -> { SurgeAPI::PhoneNumber::Campaign::AttachmentStatus }
+
+        # @!method initialize(id:, attachment_status:)
+        #   Campaign attachment details for a domestic local phone number
+        #
+        #   @param id [String] The unique identifier of the campaign this phone number is attached to
+        #
+        #   @param attachment_status [Symbol, SurgeAPI::Models::PhoneNumber::Campaign::AttachmentStatus] The current campaign attachment status for this phone number.
+
+        # The current campaign attachment status for this phone number.
+        #
+        # @see SurgeAPI::Models::PhoneNumber::Campaign#attachment_status
+        module AttachmentStatus
+          extend SurgeAPI::Internal::Type::Enum
+
+          ATTACHED = :attached
+          ATTACHMENT_PENDING = :attachment_pending
+          DETACHED = :detached
+          DETACHMENT_PENDING = :detachment_pending
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+
       # Whether the phone number is local, toll-free, or short code
       #
       # @see SurgeAPI::Models::PhoneNumber#type

data/lib/surge_api/models/phone_number_attached_to_campaign_webhook_event.rb

@@ -48,8 +48,21 @@ module SurgeAPI
         #   @return [String]
         required :id, String
 
+        # @!attribute campaign
+        #   Campaign attachment details for a domestic local phone number
+        #
+        #   @return [SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign, nil]
+        required :campaign,
+                 -> {
+                   SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign
+                 },
+                 nil?: true
+
         # @!attribute campaign_id
-        #   The unique identifier of the campaign this phone number is attached to
+        #   @deprecated Use `campaign.id` instead.
+        #
+        #   Deprecated. The unique identifier of the campaign this phone number is attached
+        #   to
         #
         #   @return [String]
         required :campaign_id, String
@@ -72,12 +85,18 @@ module SurgeAPI
         #   @return [Symbol, SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent::Data::Type]
         required :type, enum: -> { SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Type }
 
-        # @!method initialize(id:, campaign_id:, name:, number:, type:)
+        # @!method initialize(id:, campaign:, campaign_id:, name:, number:, type:)
+        #   Some parameter documentations has been truncated, see
+        #   {SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent::Data} for more
+        #   details.
+        #
         #   The data associated with the event
         #
         #   @param id [String] The unique identifier for the phone number
         #
-        #   @param campaign_id [String] The unique identifier of the campaign this phone number is attached to
+        #   @param campaign [SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign, nil] Campaign attachment details for a domestic local phone number
+        #
+        #   @param campaign_id [String] Deprecated. The unique identifier of the campaign this phone number is attached
         #
         #   @param name [String, nil] A human-readable name for the phone number
         #
@@ -85,6 +104,44 @@ module SurgeAPI
         #
         #   @param type [Symbol, SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent::Data::Type] Whether the phone number is local, toll-free, or short code
 
+        # @see SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent::Data#campaign
+        class Campaign < SurgeAPI::Internal::Type::BaseModel
+          # @!attribute id
+          #   The unique identifier of the campaign this phone number is attached to
+          #
+          #   @return [String]
+          required :id, String
+
+          # @!attribute attachment_status
+          #   The current campaign attachment status for this phone number.
+          #
+          #   @return [Symbol, SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::AttachmentStatus]
+          required :attachment_status,
+                   enum: -> { SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::AttachmentStatus }
+
+          # @!method initialize(id:, attachment_status:)
+          #   Campaign attachment details for a domestic local phone number
+          #
+          #   @param id [String] The unique identifier of the campaign this phone number is attached to
+          #
+          #   @param attachment_status [Symbol, SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::AttachmentStatus] The current campaign attachment status for this phone number.
+
+          # The current campaign attachment status for this phone number.
+          #
+          # @see SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign#attachment_status
+          module AttachmentStatus
+            extend SurgeAPI::Internal::Type::Enum
+
+            ATTACHED = :attached
+            ATTACHMENT_PENDING = :attachment_pending
+            DETACHED = :detached
+            DETACHMENT_PENDING = :detachment_pending
+
+            # @!method self.values
+            #   @return [Array<Symbol>]
+          end
+        end
+
         # Whether the phone number is local, toll-free, or short code
         #
         # @see SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent::Data#type

data/lib/surge_api/models/phone_number_list_available_numbers_params.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Models
+    # @see SurgeAPI::Resources::PhoneNumbers#list_available_numbers
+    class PhoneNumberListAvailableNumbersParams < SurgeAPI::Internal::Type::BaseModel
+      extend SurgeAPI::Internal::Type::RequestParameters::Converter
+      include SurgeAPI::Internal::Type::RequestParameters
+
+      # @!attribute account_id
+      #   The account ID to list available phone numbers for.
+      #
+      #   @return [String]
+      required :account_id, String
+
+      # @!attribute type
+      #   Whether to search for local or toll-free numbers.
+      #
+      #   @return [Symbol, SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::Type]
+      required :type, enum: -> { SurgeAPI::PhoneNumberListAvailableNumbersParams::Type }
+
+      # @!attribute after
+      #   Cursor for forward pagination. Use the next_cursor from a previous response.
+      #
+      #   @return [String, nil]
+      optional :after, String
+
+      # @!attribute area_code
+      #   Filter by 3-digit area code.
+      #
+      #   @return [String, nil]
+      optional :area_code, String
+
+      # @!attribute before
+      #   Cursor for backward pagination. Use the previous_cursor from a previous
+      #   response.
+      #
+      #   @return [String, nil]
+      optional :before, String
+
+      # @!attribute country
+      #   ISO country code to search in.
+      #
+      #   @return [Symbol, SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::Country, nil]
+      optional :country, enum: -> { SurgeAPI::PhoneNumberListAvailableNumbersParams::Country }
+
+      # @!method initialize(account_id:, type:, after: nil, area_code: nil, before: nil, country: nil, request_options: {})
+      #   Some parameter documentations has been truncated, see
+      #   {SurgeAPI::Models::PhoneNumberListAvailableNumbersParams} for more details.
+      #
+      #   @param account_id [String] The account ID to list available phone numbers for.
+      #
+      #   @param type [Symbol, SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::Type] Whether to search for local or toll-free numbers.
+      #
+      #   @param after [String] Cursor for forward pagination. Use the next_cursor from a previous response.
+      #
+      #   @param area_code [String] Filter by 3-digit area code.
+      #
+      #   @param before [String] Cursor for backward pagination. Use the previous_cursor from a previous response
+      #
+      #   @param country [Symbol, SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::Country] ISO country code to search in.
+      #
+      #   @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}]
+
+      # Whether to search for local or toll-free numbers.
+      module Type
+        extend SurgeAPI::Internal::Type::Enum
+
+        LOCAL = :local
+        TOLL_FREE = :toll_free
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+
+      # ISO country code to search in.
+      module Country
+        extend SurgeAPI::Internal::Type::Enum
+
+        US = :US
+        CA = :CA
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+    end
+  end
+end

data/lib/surge_api/models/phone_number_list_available_numbers_response.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Models
+    # @see SurgeAPI::Resources::PhoneNumbers#list_available_numbers
+    class PhoneNumberListAvailableNumbersResponse < SurgeAPI::Internal::Type::BaseModel
+      # @!attribute country
+      #   ISO country code for the phone number
+      #
+      #   @return [Symbol, SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Country]
+      required :country, enum: -> { SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Country }
+
+      # @!attribute number
+      #   The phone number in E.164 format
+      #
+      #   @return [String]
+      required :number, String
+
+      # @!attribute type
+      #   Whether the phone number is local or toll-free
+      #
+      #   @return [Symbol, SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Type]
+      required :type, enum: -> { SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Type }
+
+      # @!method initialize(country:, number:, type:)
+      #   A phone number available for purchase from Surge inventory
+      #
+      #   @param country [Symbol, SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Country] ISO country code for the phone number
+      #
+      #   @param number [String] The phone number in E.164 format
+      #
+      #   @param type [Symbol, SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Type] Whether the phone number is local or toll-free
+
+      # ISO country code for the phone number
+      #
+      # @see SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse#country
+      module Country
+        extend SurgeAPI::Internal::Type::Enum
+
+        US = :US
+        CA = :CA
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+
+      # Whether the phone number is local or toll-free
+      #
+      # @see SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse#type
+      module Type
+        extend SurgeAPI::Internal::Type::Enum
+
+        LOCAL = :local
+        TOLL_FREE = :toll_free
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+    end
+  end
+end

data/lib/surge_api/models/phone_number_purchase_params.rb

@@ -41,6 +41,13 @@ module SurgeAPI
       #   @return [String, nil]
       optional :name, String
 
+      # @!attribute phone_number
+      #   The exact phone number to purchase in E.164 format. When provided, all other
+      #   search parameters are ignored.
+      #
+      #   @return [String, nil]
+      optional :phone_number, String
+
       # @!attribute type
       #   Whether the phone number is local or toll-free. Can be omitted if area_code or
       #   latitude/longitude are provided.
@@ -48,7 +55,7 @@ module SurgeAPI
       #   @return [Symbol, SurgeAPI::Models::PhoneNumberPurchaseParams::Type, nil]
       optional :type, enum: -> { SurgeAPI::PhoneNumberPurchaseParams::Type }
 
-      # @!method initialize(account_id:, area_code: nil, latitude: nil, longitude: nil, name: nil, type: nil, request_options: {})
+      # @!method initialize(account_id:, area_code: nil, latitude: nil, longitude: nil, name: nil, phone_number: nil, type: nil, request_options: {})
       #   Some parameter documentations has been truncated, see
       #   {SurgeAPI::Models::PhoneNumberPurchaseParams} for more details.
       #
@@ -62,6 +69,8 @@ module SurgeAPI
       #
       #   @param name [String] A human-readable name for the phone number. If not provided, defaults to the for
       #
+      #   @param phone_number [String] The exact phone number to purchase in E.164 format. When provided, all other sea
+      #
       #   @param type [Symbol, SurgeAPI::Models::PhoneNumberPurchaseParams::Type] Whether the phone number is local or toll-free. Can be omitted if area_code or l
       #
       #   @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}]

data/lib/surge_api/models/phone_number_retrieve_params.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Models
+    # @see SurgeAPI::Resources::PhoneNumbers#retrieve
+    class PhoneNumberRetrieveParams < SurgeAPI::Internal::Type::BaseModel
+      extend SurgeAPI::Internal::Type::RequestParameters::Converter
+      include SurgeAPI::Internal::Type::RequestParameters
+
+      # @!attribute id
+      #   The ID of the phone number to retrieve.
+      #
+      #   @return [String]
+      required :id, String
+
+      # @!method initialize(id:, request_options: {})
+      #   @param id [String] The ID of the phone number to retrieve.
+      #
+      #   @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/surge_api/models.rb

@@ -125,12 +125,16 @@ module SurgeAPI
 
   PhoneNumberAttachedToCampaignWebhookEvent = SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent
 
+  PhoneNumberListAvailableNumbersParams = SurgeAPI::Models::PhoneNumberListAvailableNumbersParams
+
   PhoneNumberListParams = SurgeAPI::Models::PhoneNumberListParams
 
   PhoneNumberPurchaseParams = SurgeAPI::Models::PhoneNumberPurchaseParams
 
   PhoneNumberReleaseParams = SurgeAPI::Models::PhoneNumberReleaseParams
 
+  PhoneNumberRetrieveParams = SurgeAPI::Models::PhoneNumberRetrieveParams
+
   PhoneNumberUpdateParams = SurgeAPI::Models::PhoneNumberUpdateParams
 
   RecordingCompletedWebhookEvent = SurgeAPI::Models::RecordingCompletedWebhookEvent

data/lib/surge_api/resources/phone_numbers.rb

@@ -3,6 +3,26 @@
 module SurgeAPI
   module Resources
     class PhoneNumbers
+      # Retrieves a PhoneNumber object.
+      #
+      # @overload retrieve(id, request_options: {})
+      #
+      # @param id [String] The ID of the phone number to retrieve.
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Models::PhoneNumber]
+      #
+      # @see SurgeAPI::Models::PhoneNumberRetrieveParams
+      def retrieve(id, params = {})
+        @client.request(
+          method: :get,
+          path: ["phone_numbers/%1$s", id],
+          model: SurgeAPI::PhoneNumber,
+          options: params[:request_options]
+        )
+      end
+
       # Updates a phone number's details.
       #
       # @overload update(id, campaign_id: nil, name: nil, request_options: {})
@@ -60,13 +80,54 @@ module SurgeAPI
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {SurgeAPI::Models::PhoneNumberListAvailableNumbersParams} for more details.
+      #
+      # Browse purchasable phone numbers from Surge inventory before buying.
+      #
+      # Pagination cursors are always null for now.
+      #
+      # @overload list_available_numbers(account_id, type:, after: nil, area_code: nil, before: nil, country: nil, request_options: {})
+      #
+      # @param account_id [String] The account ID to list available phone numbers for.
+      #
+      # @param type [Symbol, SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::Type] Whether to search for local or toll-free numbers.
+      #
+      # @param after [String] Cursor for forward pagination. Use the next_cursor from a previous response.
+      #
+      # @param area_code [String] Filter by 3-digit area code.
+      #
+      # @param before [String] Cursor for backward pagination. Use the previous_cursor from a previous response
+      #
+      # @param country [Symbol, SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::Country] ISO country code to search in.
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Internal::Cursor<SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse>]
+      #
+      # @see SurgeAPI::Models::PhoneNumberListAvailableNumbersParams
+      def list_available_numbers(account_id, params)
+        parsed, options = SurgeAPI::PhoneNumberListAvailableNumbersParams.dump_request(params)
+        query = SurgeAPI::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: ["accounts/%1$s/available_phone_numbers", account_id],
+          query: query,
+          page: SurgeAPI::Internal::Cursor,
+          model: SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse,
+          options: options
+        )
+      end
+
       # Some parameter documentations has been truncated, see
       # {SurgeAPI::Models::PhoneNumberPurchaseParams} for more details.
       #
-      # Purchase a new phone number for the account. You can specify search criteria or
-      # let the system select a random number.
+      # Purchase a new phone number for the account. You can specify an exact phone
+      # number, search criteria, or let the system select a random number.
       #
-      # @overload purchase(account_id, area_code: nil, latitude: nil, longitude: nil, name: nil, type: nil, request_options: {})
+      # When `phone_number` is provided, all other search parameters are ignored.
+      #
+      # @overload purchase(account_id, area_code: nil, latitude: nil, longitude: nil, name: nil, phone_number: nil, type: nil, request_options: {})
       #
       # @param account_id [String] The account for which the phone number should be created.
       #
@@ -78,6 +139,8 @@ module SurgeAPI
       #
       # @param name [String] A human-readable name for the phone number. If not provided, defaults to the for
       #
+      # @param phone_number [String] The exact phone number to purchase in E.164 format. When provided, all other sea
+      #
       # @param type [Symbol, SurgeAPI::Models::PhoneNumberPurchaseParams::Type] Whether the phone number is local or toll-free. Can be omitted if area_code or l
       #
       # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]

data/lib/surge_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SurgeAPI
-  VERSION = "0.19.0"
+  VERSION = "0.20.0"
 end

data/lib/surge_api.rb

@@ -99,9 +99,12 @@ require_relative "surge_api/models/message_sent_webhook_event"
 require_relative "surge_api/models/organization"
 require_relative "surge_api/models/phone_number"
 require_relative "surge_api/models/phone_number_attached_to_campaign_webhook_event"
+require_relative "surge_api/models/phone_number_list_available_numbers_params"
+require_relative "surge_api/models/phone_number_list_available_numbers_response"
 require_relative "surge_api/models/phone_number_list_params"
 require_relative "surge_api/models/phone_number_purchase_params"
 require_relative "surge_api/models/phone_number_release_params"
+require_relative "surge_api/models/phone_number_retrieve_params"
 require_relative "surge_api/models/phone_number_update_params"
 require_relative "surge_api/models/recording_completed_webhook_event"
 require_relative "surge_api/models/recording_delete_params"