rcs 1.0.17 → 2.0.0.pre.rc.1

data/lib/rcs/messages/types/message_reaction_schema_options.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "ostruct"
+require "json"
+
+module Pinnacle
+  module Messages
+    module Types
+      class MessageReactionSchemaOptions
+        # @return [Boolean] By default, only messages sent with the `options.tracking` field can be
+        #  precisely reacted to. <br>
+        #  Set `options.force` to true to bypass this restriction (may react to a different
+        #  message). <br>
+        #  For MMS and RCS, only messages containing text can be tracked. Otherwise,
+        #  `options.force` is ignored.
+        attr_reader :force
+        # @return [OpenStruct] Additional properties unmapped to the current class definition
+        attr_reader :additional_properties
+        # @return [Object]
+        attr_reader :_field_set
+        protected :_field_set
+
+        OMIT = Object.new
+
+        # @param force [Boolean] By default, only messages sent with the `options.tracking` field can be
+        #  precisely reacted to. <br>
+        #  Set `options.force` to true to bypass this restriction (may react to a different
+        #  message). <br>
+        #  For MMS and RCS, only messages containing text can be tracked. Otherwise,
+        #  `options.force` is ignored.
+        # @param additional_properties [OpenStruct] Additional properties unmapped to the current class definition
+        # @return [Pinnacle::Messages::Types::MessageReactionSchemaOptions]
+        def initialize(force: OMIT, additional_properties: nil)
+          @force = force if force != OMIT
+          @additional_properties = additional_properties
+          @_field_set = { "force": force }.reject do |_k, v|
+            v == OMIT
+          end
+        end
+
+        # Deserialize a JSON object to an instance of MessageReactionSchemaOptions
+        #
+        # @param json_object [String]
+        # @return [Pinnacle::Messages::Types::MessageReactionSchemaOptions]
+        def self.from_json(json_object:)
+          struct = JSON.parse(json_object, object_class: OpenStruct)
+          parsed_json = JSON.parse(json_object)
+          force = parsed_json["force"]
+          new(force: force, additional_properties: struct)
+        end
+
+        # Serialize an instance of MessageReactionSchemaOptions to a JSON object
+        #
+        # @return [String]
+        def to_json(*_args)
+          @_field_set&.to_json
+        end
+
+        # Leveraged for Union-type generation, validate_raw attempts to parse the given
+        #  hash and check each fields type against the current object's property
+        #  definitions.
+        #
+        # @param obj [Object]
+        # @return [Void]
+        def self.validate_raw(obj:)
+          obj.force&.is_a?(Boolean) != false || raise("Passed value for field obj.force is not the expected type, validation failed.")
+        end
+      end
+    end
+  end
+end

data/lib/rcs/phone_numbers/campaign/client.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require_relative "../../../requests"
+require_relative "../../types/messaging_profile_enum"
+require_relative "../../types/attached_phone_number_result"
+require_relative "../../types/detached_phone_number_result"
+require "async"
+
+module Pinnacle
+  module PhoneNumbers
+    class CampaignClient
+      # @return [Pinnacle::RequestClient]
+      attr_reader :request_client
+
+      # @param request_client [Pinnacle::RequestClient]
+      # @return [Pinnacle::PhoneNumbers::CampaignClient]
+      def initialize(request_client:)
+        @request_client = request_client
+      end
+
+      # Link a phone number to a specific campaign.
+      #
+      # @param phones [Array<String>] List of phone number (E.164 format).
+      # @param campaign_type [Pinnacle::Types::MessagingProfileEnum]
+      # @param campaign_id [Integer] Campaign's identifier.
+      # @param request_options [Pinnacle::RequestOptions]
+      # @return [Pinnacle::Types::AttachedPhoneNumberResult]
+      # @example
+      #  api = Pinnacle::Client.new(
+      #    base_url: "https://api.example.com",
+      #    environment: Pinnacle::Environment::DEFAULT,
+      #    api_key: "YOUR_API_KEY"
+      #  )
+      #  api.phone_numbers.campaign.attach(
+      #    phones: ["+14155550123", "+14155559876", "+14155550111"],
+      #    campaign_type: TOLL_FREE,
+      #    campaign_id: 101
+      #  )
+      def attach(phones:, campaign_type:, campaign_id:, request_options: nil)
+        response = @request_client.conn.post do |req|
+          req.options.timeout = request_options.timeout_in_seconds unless request_options&.timeout_in_seconds.nil?
+          req.headers["PINNACLE-API-KEY"] = request_options.api_key unless request_options&.api_key.nil?
+          req.headers = {
+        **(req.headers || {}),
+        **@request_client.get_headers,
+        **(request_options&.additional_headers || {})
+          }.compact
+          unless request_options.nil? || request_options&.additional_query_parameters.nil?
+            req.params = { **(request_options&.additional_query_parameters || {}) }.compact
+          end
+          req.body = {
+            **(request_options&.additional_body_parameters || {}),
+            phones: phones,
+            campaignType: campaign_type,
+            campaignId: campaign_id
+          }.compact
+          req.url "#{@request_client.get_url(request_options: request_options)}/phone-numbers/attach-campaign"
+        end
+        Pinnacle::Types::AttachedPhoneNumberResult.from_json(json_object: response.body)
+      end
+
+      # Remove the association between a phone number and its attached campaign.
+      #
+      # @param phones [Array<String>] List of phone numbers (E.164 format).
+      # @param request_options [Pinnacle::RequestOptions]
+      # @return [Pinnacle::Types::DetachedPhoneNumberResult]
+      # @example
+      #  api = Pinnacle::Client.new(
+      #    base_url: "https://api.example.com",
+      #    environment: Pinnacle::Environment::DEFAULT,
+      #    api_key: "YOUR_API_KEY"
+      #  )
+      #  api.phone_numbers.campaign.detach(phones: ["+14155559876", "14155550111"])
+      def detach(phones:, request_options: nil)
+        response = @request_client.conn.delete do |req|
+          req.options.timeout = request_options.timeout_in_seconds unless request_options&.timeout_in_seconds.nil?
+          req.headers["PINNACLE-API-KEY"] = request_options.api_key unless request_options&.api_key.nil?
+          req.headers = {
+        **(req.headers || {}),
+        **@request_client.get_headers,
+        **(request_options&.additional_headers || {})
+          }.compact
+          unless request_options.nil? || request_options&.additional_query_parameters.nil?
+            req.params = { **(request_options&.additional_query_parameters || {}) }.compact
+          end
+          req.body = { **(request_options&.additional_body_parameters || {}), phones: phones }.compact
+          req.url "#{@request_client.get_url(request_options: request_options)}/phone-numbers/detach-campaign"
+        end
+        Pinnacle::Types::DetachedPhoneNumberResult.from_json(json_object: response.body)
+      end
+    end
+
+    class AsyncCampaignClient
+      # @return [Pinnacle::AsyncRequestClient]
+      attr_reader :request_client
+
+      # @param request_client [Pinnacle::AsyncRequestClient]
+      # @return [Pinnacle::PhoneNumbers::AsyncCampaignClient]
+      def initialize(request_client:)
+        @request_client = request_client
+      end
+
+      # Link a phone number to a specific campaign.
+      #
+      # @param phones [Array<String>] List of phone number (E.164 format).
+      # @param campaign_type [Pinnacle::Types::MessagingProfileEnum]
+      # @param campaign_id [Integer] Campaign's identifier.
+      # @param request_options [Pinnacle::RequestOptions]
+      # @return [Pinnacle::Types::AttachedPhoneNumberResult]
+      # @example
+      #  api = Pinnacle::Client.new(
+      #    base_url: "https://api.example.com",
+      #    environment: Pinnacle::Environment::DEFAULT,
+      #    api_key: "YOUR_API_KEY"
+      #  )
+      #  api.phone_numbers.campaign.attach(
+      #    phones: ["+14155550123", "+14155559876", "+14155550111"],
+      #    campaign_type: TOLL_FREE,
+      #    campaign_id: 101
+      #  )
+      def attach(phones:, campaign_type:, campaign_id:, request_options: nil)
+        Async do
+          response = @request_client.conn.post do |req|
+            req.options.timeout = request_options.timeout_in_seconds unless request_options&.timeout_in_seconds.nil?
+            req.headers["PINNACLE-API-KEY"] = request_options.api_key unless request_options&.api_key.nil?
+            req.headers = {
+          **(req.headers || {}),
+          **@request_client.get_headers,
+          **(request_options&.additional_headers || {})
+            }.compact
+            unless request_options.nil? || request_options&.additional_query_parameters.nil?
+              req.params = { **(request_options&.additional_query_parameters || {}) }.compact
+            end
+            req.body = {
+              **(request_options&.additional_body_parameters || {}),
+              phones: phones,
+              campaignType: campaign_type,
+              campaignId: campaign_id
+            }.compact
+            req.url "#{@request_client.get_url(request_options: request_options)}/phone-numbers/attach-campaign"
+          end
+          Pinnacle::Types::AttachedPhoneNumberResult.from_json(json_object: response.body)
+        end
+      end
+
+      # Remove the association between a phone number and its attached campaign.
+      #
+      # @param phones [Array<String>] List of phone numbers (E.164 format).
+      # @param request_options [Pinnacle::RequestOptions]
+      # @return [Pinnacle::Types::DetachedPhoneNumberResult]
+      # @example
+      #  api = Pinnacle::Client.new(
+      #    base_url: "https://api.example.com",
+      #    environment: Pinnacle::Environment::DEFAULT,
+      #    api_key: "YOUR_API_KEY"
+      #  )
+      #  api.phone_numbers.campaign.detach(phones: ["+14155559876", "14155550111"])
+      def detach(phones:, request_options: nil)
+        Async do
+          response = @request_client.conn.delete do |req|
+            req.options.timeout = request_options.timeout_in_seconds unless request_options&.timeout_in_seconds.nil?
+            req.headers["PINNACLE-API-KEY"] = request_options.api_key unless request_options&.api_key.nil?
+            req.headers = {
+          **(req.headers || {}),
+          **@request_client.get_headers,
+          **(request_options&.additional_headers || {})
+            }.compact
+            unless request_options.nil? || request_options&.additional_query_parameters.nil?
+              req.params = { **(request_options&.additional_query_parameters || {}) }.compact
+            end
+            req.body = { **(request_options&.additional_body_parameters || {}), phones: phones }.compact
+            req.url "#{@request_client.get_url(request_options: request_options)}/phone-numbers/detach-campaign"
+          end
+          Pinnacle::Types::DetachedPhoneNumberResult.from_json(json_object: response.body)
+        end
+      end
+    end
+  end
+end

data/lib/rcs/phone_numbers/client.rb

@@ -0,0 +1,345 @@
+# frozen_string_literal: true
+
+require_relative "../../requests"
+require_relative "../types/phone_feature_enum"
+require_relative "types/search_schema_location"
+require_relative "types/search_schema_number"
+require_relative "types/search_schema_options"
+require_relative "../types/phone_enum"
+require_relative "../types/phone_number_details"
+require "json"
+require_relative "../types/purchased_number"
+require_relative "types/phone_details_schema_level"
+require_relative "types/phone_details_schema_options"
+require_relative "types/phone_numbers_get_response"
+require "async"
+
+module Pinnacle
+  class PhoneNumbersClient
+    # @return [Pinnacle::RequestClient]
+    attr_reader :request_client
+
+    # @param request_client [Pinnacle::RequestClient]
+    # @return [Pinnacle::PhoneNumbersClient]
+    def initialize(request_client:)
+      @request_client = request_client
+    end
+
+    # Search for available phone numbers that match your exact criteria.
+    #
+    # @param features [Array<Pinnacle::Types::PhoneFeatureEnum>]
+    # @param location [Hash] Filter your search by geographic location to find numbers in specific regions.
+    #  <br>
+    #  Toll-free numbers ignore city and state filters.Request of type Pinnacle::PhoneNumbers::Types::SearchSchemaLocation, as a Hash
+    #   * :city (String)
+    #   * :country_code (String)
+    #   * :national_destination_code (String)
+    #   * :state (String)
+    # @param phone_number_digit_filters [Hash] Filter your search by digit pattern.Request of type Pinnacle::PhoneNumbers::Types::SearchSchemaNumber, as a Hash
+    #   * :contains (String)
+    #   * :ends_with (String)
+    #   * :starts_with (String)
+    # @param options [Hash] Extra search settings to control how many results you get.Request of type Pinnacle::PhoneNumbers::Types::SearchSchemaOptions, as a Hash
+    #   * :limit (Integer)
+    # @param type [Array<Pinnacle::Types::PhoneEnum>] Types of phone numbers to return in your search.
+    # @param request_options [Pinnacle::RequestOptions]
+    # @return [Array<Pinnacle::Types::PhoneNumberDetails>]
+    # @example
+    #  api = Pinnacle::Client.new(
+    #    base_url: "https://api.example.com",
+    #    environment: Pinnacle::Environment::DEFAULT,
+    #    api_key: "YOUR_API_KEY"
+    #  )
+    #  api.phone_numbers.search(
+    #    features: [SMS, MMS],
+    #    location: { city: "New York", national_destination_code: "212" },
+    #    phone_number_digit_filters: { contains: "514", starts_with: "45" },
+    #    options: { limit: 4 },
+    #    type: [LOCAL]
+    #  )
+    def search(type:, features: nil, location: nil, phone_number_digit_filters: nil, options: nil, request_options: nil)
+      response = @request_client.conn.post do |req|
+        req.options.timeout = request_options.timeout_in_seconds unless request_options&.timeout_in_seconds.nil?
+        req.headers["PINNACLE-API-KEY"] = request_options.api_key unless request_options&.api_key.nil?
+        req.headers = {
+      **(req.headers || {}),
+      **@request_client.get_headers,
+      **(request_options&.additional_headers || {})
+        }.compact
+        unless request_options.nil? || request_options&.additional_query_parameters.nil?
+          req.params = { **(request_options&.additional_query_parameters || {}) }.compact
+        end
+        req.body = {
+          **(request_options&.additional_body_parameters || {}),
+          features: features,
+          location: location,
+          number: phone_number_digit_filters,
+          options: options,
+          type: type
+        }.compact
+        req.url "#{@request_client.get_url(request_options: request_options)}/phone-numbers/search"
+      end
+      parsed_json = JSON.parse(response.body)
+      parsed_json&.map do |item|
+        item = item.to_json
+        Pinnacle::Types::PhoneNumberDetails.from_json(json_object: item)
+      end
+    end
+
+    # Purchase one or more phone numbers found through the [search
+    #  endpoint](./search). <br>
+    #  Billing uses your account credits and the numbers are ready for immediate use.
+    #
+    # @param numbers [Array<String>] List of phone numbers you want to purchase, each in international E.164 format.
+    #  <br>
+    #  All specified numbers must be currently available and will be validated for
+    #  availability before processing the purchase. <br>
+    #  If any number in the request is unavailable or invalid, no purchases will be
+    #  made and the request will be voided.
+    # @param request_options [Pinnacle::RequestOptions]
+    # @return [Array<Pinnacle::Types::PurchasedNumber>]
+    # @example
+    #  api = Pinnacle::Client.new(
+    #    base_url: "https://api.example.com",
+    #    environment: Pinnacle::Environment::DEFAULT,
+    #    api_key: "YOUR_API_KEY"
+    #  )
+    #  api.phone_numbers.buy(numbers: ["+18559491727"])
+    def buy(numbers:, request_options: nil)
+      response = @request_client.conn.post do |req|
+        req.options.timeout = request_options.timeout_in_seconds unless request_options&.timeout_in_seconds.nil?
+        req.headers["PINNACLE-API-KEY"] = request_options.api_key unless request_options&.api_key.nil?
+        req.headers = {
+      **(req.headers || {}),
+      **@request_client.get_headers,
+      **(request_options&.additional_headers || {})
+        }.compact
+        unless request_options.nil? || request_options&.additional_query_parameters.nil?
+          req.params = { **(request_options&.additional_query_parameters || {}) }.compact
+        end
+        req.body = { **(request_options&.additional_body_parameters || {}), numbers: numbers }.compact
+        req.url "#{@request_client.get_url(request_options: request_options)}/phone-numbers/buy"
+      end
+      parsed_json = JSON.parse(response.body)
+      parsed_json&.map do |item|
+        item = item.to_json
+        Pinnacle::Types::PurchasedNumber.from_json(json_object: item)
+      end
+    end
+
+    # Retrieve information about any phone number.
+    #
+    # @param phone [String] Phone number you want to analyze in E.164 format.
+    # @param level [Pinnacle::PhoneNumbers::Types::PhoneDetailsSchemaLevel] Choose how much detail you want in your results:
+    #  - `basic`: Receive essential info like carrier, location, and format.
+    #  - `advanced`: Receive a deeper analysis including fraud risk, detailed location,
+    #  and enhanced contact info.
+    # @param options [Hash] Customize your lookup with additional options.Request of type Pinnacle::PhoneNumbers::Types::PhoneDetailsSchemaOptions, as a Hash
+    #   * :force (Boolean)
+    #   * :risk (Boolean)
+    #   * :enhanced_contact_info (Hash)
+    #     * :context (String)
+    # @param request_options [Pinnacle::RequestOptions]
+    # @return [Pinnacle::Types::BasicPhoneInformation, Pinnacle::Types::AdvancedPhoneInformation]
+    # @example
+    #  api = Pinnacle::Client.new(
+    #    base_url: "https://api.example.com",
+    #    environment: Pinnacle::Environment::DEFAULT,
+    #    api_key: "YOUR_API_KEY"
+    #  )
+    #  api.phone_numbers.get(
+    #    phone: "+11234567890",
+    #    level: ADVANCED,
+    #    options: { risk: true, enhanced_contact_info: { context: "This is my friend from JZ. He has done a lot in the crypto space." } }
+    #  )
+    def get(phone:, level:, options: nil, request_options: nil)
+      response = @request_client.conn.post do |req|
+        req.options.timeout = request_options.timeout_in_seconds unless request_options&.timeout_in_seconds.nil?
+        req.headers["PINNACLE-API-KEY"] = request_options.api_key unless request_options&.api_key.nil?
+        req.headers = {
+      **(req.headers || {}),
+      **@request_client.get_headers,
+      **(request_options&.additional_headers || {})
+        }.compact
+        unless request_options.nil? || request_options&.additional_query_parameters.nil?
+          req.params = { **(request_options&.additional_query_parameters || {}) }.compact
+        end
+        req.body = {
+          **(request_options&.additional_body_parameters || {}),
+          phone: phone,
+          level: level,
+          options: options
+        }.compact
+        req.url "#{@request_client.get_url(request_options: request_options)}/phone-numbers/details"
+      end
+      Pinnacle::PhoneNumbers::Types::PhoneNumbersGetResponse.from_json(json_object: response.body)
+    end
+  end
+
+  class AsyncPhoneNumbersClient
+    # @return [Pinnacle::AsyncRequestClient]
+    attr_reader :request_client
+
+    # @param request_client [Pinnacle::AsyncRequestClient]
+    # @return [Pinnacle::AsyncPhoneNumbersClient]
+    def initialize(request_client:)
+      @request_client = request_client
+    end
+
+    # Search for available phone numbers that match your exact criteria.
+    #
+    # @param features [Array<Pinnacle::Types::PhoneFeatureEnum>]
+    # @param location [Hash] Filter your search by geographic location to find numbers in specific regions.
+    #  <br>
+    #  Toll-free numbers ignore city and state filters.Request of type Pinnacle::PhoneNumbers::Types::SearchSchemaLocation, as a Hash
+    #   * :city (String)
+    #   * :country_code (String)
+    #   * :national_destination_code (String)
+    #   * :state (String)
+    # @param phone_number_digit_filters [Hash] Filter your search by digit pattern.Request of type Pinnacle::PhoneNumbers::Types::SearchSchemaNumber, as a Hash
+    #   * :contains (String)
+    #   * :ends_with (String)
+    #   * :starts_with (String)
+    # @param options [Hash] Extra search settings to control how many results you get.Request of type Pinnacle::PhoneNumbers::Types::SearchSchemaOptions, as a Hash
+    #   * :limit (Integer)
+    # @param type [Array<Pinnacle::Types::PhoneEnum>] Types of phone numbers to return in your search.
+    # @param request_options [Pinnacle::RequestOptions]
+    # @return [Array<Pinnacle::Types::PhoneNumberDetails>]
+    # @example
+    #  api = Pinnacle::Client.new(
+    #    base_url: "https://api.example.com",
+    #    environment: Pinnacle::Environment::DEFAULT,
+    #    api_key: "YOUR_API_KEY"
+    #  )
+    #  api.phone_numbers.search(
+    #    features: [SMS, MMS],
+    #    location: { city: "New York", national_destination_code: "212" },
+    #    phone_number_digit_filters: { contains: "514", starts_with: "45" },
+    #    options: { limit: 4 },
+    #    type: [LOCAL]
+    #  )
+    def search(type:, features: nil, location: nil, phone_number_digit_filters: nil, options: nil, request_options: nil)
+      Async do
+        response = @request_client.conn.post do |req|
+          req.options.timeout = request_options.timeout_in_seconds unless request_options&.timeout_in_seconds.nil?
+          req.headers["PINNACLE-API-KEY"] = request_options.api_key unless request_options&.api_key.nil?
+          req.headers = {
+        **(req.headers || {}),
+        **@request_client.get_headers,
+        **(request_options&.additional_headers || {})
+          }.compact
+          unless request_options.nil? || request_options&.additional_query_parameters.nil?
+            req.params = { **(request_options&.additional_query_parameters || {}) }.compact
+          end
+          req.body = {
+            **(request_options&.additional_body_parameters || {}),
+            features: features,
+            location: location,
+            number: phone_number_digit_filters,
+            options: options,
+            type: type
+          }.compact
+          req.url "#{@request_client.get_url(request_options: request_options)}/phone-numbers/search"
+        end
+        parsed_json = JSON.parse(response.body)
+        parsed_json&.map do |item|
+          item = item.to_json
+          Pinnacle::Types::PhoneNumberDetails.from_json(json_object: item)
+        end
+      end
+    end
+
+    # Purchase one or more phone numbers found through the [search
+    #  endpoint](./search). <br>
+    #  Billing uses your account credits and the numbers are ready for immediate use.
+    #
+    # @param numbers [Array<String>] List of phone numbers you want to purchase, each in international E.164 format.
+    #  <br>
+    #  All specified numbers must be currently available and will be validated for
+    #  availability before processing the purchase. <br>
+    #  If any number in the request is unavailable or invalid, no purchases will be
+    #  made and the request will be voided.
+    # @param request_options [Pinnacle::RequestOptions]
+    # @return [Array<Pinnacle::Types::PurchasedNumber>]
+    # @example
+    #  api = Pinnacle::Client.new(
+    #    base_url: "https://api.example.com",
+    #    environment: Pinnacle::Environment::DEFAULT,
+    #    api_key: "YOUR_API_KEY"
+    #  )
+    #  api.phone_numbers.buy(numbers: ["+18559491727"])
+    def buy(numbers:, request_options: nil)
+      Async do
+        response = @request_client.conn.post do |req|
+          req.options.timeout = request_options.timeout_in_seconds unless request_options&.timeout_in_seconds.nil?
+          req.headers["PINNACLE-API-KEY"] = request_options.api_key unless request_options&.api_key.nil?
+          req.headers = {
+        **(req.headers || {}),
+        **@request_client.get_headers,
+        **(request_options&.additional_headers || {})
+          }.compact
+          unless request_options.nil? || request_options&.additional_query_parameters.nil?
+            req.params = { **(request_options&.additional_query_parameters || {}) }.compact
+          end
+          req.body = { **(request_options&.additional_body_parameters || {}), numbers: numbers }.compact
+          req.url "#{@request_client.get_url(request_options: request_options)}/phone-numbers/buy"
+        end
+        parsed_json = JSON.parse(response.body)
+        parsed_json&.map do |item|
+          item = item.to_json
+          Pinnacle::Types::PurchasedNumber.from_json(json_object: item)
+        end
+      end
+    end
+
+    # Retrieve information about any phone number.
+    #
+    # @param phone [String] Phone number you want to analyze in E.164 format.
+    # @param level [Pinnacle::PhoneNumbers::Types::PhoneDetailsSchemaLevel] Choose how much detail you want in your results:
+    #  - `basic`: Receive essential info like carrier, location, and format.
+    #  - `advanced`: Receive a deeper analysis including fraud risk, detailed location,
+    #  and enhanced contact info.
+    # @param options [Hash] Customize your lookup with additional options.Request of type Pinnacle::PhoneNumbers::Types::PhoneDetailsSchemaOptions, as a Hash
+    #   * :force (Boolean)
+    #   * :risk (Boolean)
+    #   * :enhanced_contact_info (Hash)
+    #     * :context (String)
+    # @param request_options [Pinnacle::RequestOptions]
+    # @return [Pinnacle::Types::BasicPhoneInformation, Pinnacle::Types::AdvancedPhoneInformation]
+    # @example
+    #  api = Pinnacle::Client.new(
+    #    base_url: "https://api.example.com",
+    #    environment: Pinnacle::Environment::DEFAULT,
+    #    api_key: "YOUR_API_KEY"
+    #  )
+    #  api.phone_numbers.get(
+    #    phone: "+11234567890",
+    #    level: ADVANCED,
+    #    options: { risk: true, enhanced_contact_info: { context: "This is my friend from JZ. He has done a lot in the crypto space." } }
+    #  )
+    def get(phone:, level:, options: nil, request_options: nil)
+      Async do
+        response = @request_client.conn.post do |req|
+          req.options.timeout = request_options.timeout_in_seconds unless request_options&.timeout_in_seconds.nil?
+          req.headers["PINNACLE-API-KEY"] = request_options.api_key unless request_options&.api_key.nil?
+          req.headers = {
+        **(req.headers || {}),
+        **@request_client.get_headers,
+        **(request_options&.additional_headers || {})
+          }.compact
+          unless request_options.nil? || request_options&.additional_query_parameters.nil?
+            req.params = { **(request_options&.additional_query_parameters || {}) }.compact
+          end
+          req.body = {
+            **(request_options&.additional_body_parameters || {}),
+            phone: phone,
+            level: level,
+            options: options
+          }.compact
+          req.url "#{@request_client.get_url(request_options: request_options)}/phone-numbers/details"
+        end
+        Pinnacle::PhoneNumbers::Types::PhoneNumbersGetResponse.from_json(json_object: response.body)
+      end
+    end
+  end
+end

data/lib/rcs/phone_numbers/types/phone_details_schema_level.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module PhoneNumbers
+    module Types
+      # Choose how much detail you want in your results:
+      #  - `basic`: Receive essential info like carrier, location, and format.
+      #  - `advanced`: Receive a deeper analysis including fraud risk, detailed location,
+      #  and enhanced contact info.
+      class PhoneDetailsSchemaLevel
+        BASIC = "basic"
+        ADVANCED = "advanced"
+      end
+    end
+  end
+end