rcs 2.0.21 → 2.0.22.pre.rc.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa587a023b2f42d4e52973dfd7f3b234494cdfe661b8c756337172bfa4def1eb
-  data.tar.gz: 0b52f0f7ceeed61cadf529a7a8b3ba606d855ec76d22a94bcb31d162a1ea7a5f
+  metadata.gz: f6d19dac500402b5f28b4cc9117ebb14ab0692ca03f197f59b14d805e724c422
+  data.tar.gz: e03cc25e82a1657cfcc9744167ad349d83a1df58c39a8c82d203ce938b2fe395
 SHA512:
-  metadata.gz: 7feff411555ed1af41d9eab7c8fbf64f72f0176fac321fbb4ffbad23360e0e204f2ca3e66470ba1b56fb6e5540d0b1e49e13d6cdd37be0627819c8fa29015d47
-  data.tar.gz: 97f9b374e2c6b28bf8b0c44276a52264c63dfe6d72f1bd901c7901d5bb2db4f4eab41a97d0ea02febd372e512f6c0c70a5d6dfc3f8290f499def4758a51b403a
+  metadata.gz: 20900184fd1576895e5308831d377869983bdbfb3efff26128d0f39bec2b60240c7c7699f5f2d460fcbd59dabfa771422d11caa0ef6fd82e90eb521ffba3215f
+  data.tar.gz: 5c060f0d6688bb6bf3e88432b325369dff246dd130b1c7d64e31d12bb97b95a47200f34d3582a96d32a182476dde6c7a33c469d80d55686f6afafc56a60daffb

data/.fernignore

@@ -1,9 +1,11 @@
 # Specify files that shouldn't be modified by Fern
 README.md
+CONTRIBUTING.md
 lib/pinnacle/wrapper
 lib/pinnacle/pinnacle_client.rb
 lib/rcs.rb
 .github/workflows/ci.yml
+.github/workflows/regenerate-sdk.yml
 .fern/replay.lock
 .fern/replay.yml
 .gitattributes

data/CONTRIBUTING.md

@@ -49,7 +49,7 @@ bundle exec rubocop -a
 
 ## About Generated Code
 
-**Important**: Most files in this SDK are automatically generated by [Fern](https://buildwithfern.com) from the API definition. Direct modifications to generated files will be overwritten the next time the SDK is generated.
+**Important**: Most files in this SDK are automatically generated from Pinnacle's API definition by the repository-owned SDK pipeline. Direct modifications to generated files will be overwritten the next time the SDK is generated.
 
 ### Generated Files
 
@@ -69,18 +69,15 @@ For custom code that should persist across SDK regenerations:
 2. Add file patterns for files you want to preserve (similar to `.gitignore` syntax)
 3. Add your custom code to those files
 
-Files listed in `.fernignore` will not be overwritten when the SDK is regenerated.
+Files and patterns listed in `.fernignore` will not be overwritten when the SDK is regenerated.
 
-For more information, see the [Fern documentation on custom code](https://buildwithfern.com/learn/sdks/overview/custom-code).
-
-#### Option 2: Contribute to the Generator
+#### Option 2: Change the Generator
 
 If you want to change how code is generated for all users of this SDK:
 
-1. The Ruby SDK generator lives in the [Fern repository](https://github.com/fern-api/fern)
-2. Generator code is located at `generators/ruby-v2/`
-3. Follow the [Fern contributing guidelines](https://github.com/fern-api/fern/blob/main/CONTRIBUTING.md)
-4. Submit a pull request with your changes to the generator
+1. Open an issue in this repository describing the generator-wide change.
+2. Pinnacle maintainers update the private generator source and generation workflow.
+3. The regenerated SDK is reviewed and tested in this repository before release.
 
 This approach is best for:
 - Bug fixes in generated code
@@ -111,9 +108,8 @@ This project uses RuboCop for code formatting. Run `bundle exec rubocop` before
 
 If you have questions or run into issues:
 
-1. Check the [Fern documentation](https://buildwithfern.com)
-2. Search existing [GitHub issues](https://github.com/fern-api/fern/issues)
-3. Open a new issue if your question hasn't been addressed
+1. Search existing issues in this repository.
+2. Open a new issue if your question has not been addressed.
 
 ## License
 

data/README.md

@@ -4,7 +4,7 @@ The Pinnacle Ruby library provides access to the Pinnacle API from Ruby.
 
 ## Documentation
 
-API reference documentation is available [here](docs.trypinnacle.app).
+API reference documentation is available at [docs.pinnacle.sh](https://docs.pinnacle.sh).
 
 ## Installation
 

data/lib/pinnacle/calls/client.rb

@@ -0,0 +1,386 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Calls
+    class Client
+      # @param client [Pinnacle::Internal::Http::RawClient]
+      #
+      # @return [void]
+      def initialize(client:)
+        @client = client
+      end
+
+      # List voice calls for your team. Results are sorted newest first.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [Integer, nil] :limit
+      # @option params [String, nil] :cursor
+      # @option params [Pinnacle::Types::CallState, nil] :state
+      # @option params [Pinnacle::Types::CallDirection, nil] :direction
+      # @option params [String, nil] :from
+      # @option params [String, nil] :to
+      # @option params [String, nil] :created_after
+      # @option params [String, nil] :created_before
+      #
+      # @return [Pinnacle::Types::ListCallsResponse]
+      def list(request_options: {}, **params)
+        params = Pinnacle::Internal::Types::Utils.normalize_keys(params)
+        query_params = {}
+        query_params["limit"] = params[:limit] if params.key?(:limit)
+        query_params["cursor"] = params[:cursor] if params.key?(:cursor)
+        query_params["state"] = params[:state] if params.key?(:state)
+        query_params["direction"] = params[:direction] if params.key?(:direction)
+        query_params["from"] = params[:from] if params.key?(:from)
+        query_params["to"] = params[:to] if params.key?(:to)
+        query_params["created_after"] = params[:created_after] if params.key?(:created_after)
+        query_params["created_before"] = params[:created_before] if params.key?(:created_before)
+
+        request = Pinnacle::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "calls",
+          query: query_params,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Pinnacle::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Pinnacle::Types::ListCallsResponse.load(response.body)
+        else
+          error_class = Pinnacle::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Start an outbound voice call from a voice-enabled phone number owned by
+      # your team.
+      #
+      # **Retrying safely.** Send an `Idempotency-Key` header and the call is
+      # placed at most once, however many times the request is repeated. This
+      # matters more here than on most endpoints: a retry without one dials the
+      # recipient a second time.
+      #
+      # - Same key, same request: returns the original call with `200` instead
+      #   of `201`, and no new call is placed.
+      # - Same key, different request: `422`. The key is bound to the request
+      #   it was first used with, so returning the unrelated original call
+      #   would be worse than refusing.
+      # - Same key while the first attempt is still in flight: `409`. Retry
+      #   once it settles.
+      #
+      # Keys are scoped to your team and expire after 24 hours. Two requests
+      # count as the same when `to`, `from`, `record` and `metadata` match;
+      # metadata key order is not significant.
+      #
+      # @param request_options [Hash]
+      # @param params [Pinnacle::Calls::Types::CreateCallParams]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String, nil] :idempotency_key
+      #
+      # @return [Pinnacle::Types::CreatedCall]
+      def create(request_options: {}, **params)
+        params = Pinnacle::Internal::Types::Utils.normalize_keys(params)
+        request_data = Pinnacle::Calls::Types::CreateCallParams.new(params).to_h
+        non_body_param_names = %w[Idempotency-Key]
+        body = request_data.except(*non_body_param_names)
+
+        headers = {}
+        headers["Idempotency-Key"] = params[:idempotency_key] if params[:idempotency_key]
+
+        request = Pinnacle::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "calls",
+          headers: headers,
+          body: body,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Pinnacle::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Pinnacle::Types::CreatedCall.load(response.body)
+        else
+          error_class = Pinnacle::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Retrieve one voice call by its Pinnacle call ID.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :id
+      #
+      # @return [Pinnacle::Types::Call]
+      def get(request_options: {}, **params)
+        params = Pinnacle::Internal::Types::Utils.normalize_keys(params)
+        request = Pinnacle::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "calls/#{URI.encode_uri_component(params[:id].to_s)}",
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Pinnacle::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Pinnacle::Types::Call.load(response.body)
+        else
+          error_class = Pinnacle::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # End a live call. Terminal calls are returned unchanged.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :id
+      #
+      # @return [Pinnacle::Types::Call]
+      def cancel(request_options: {}, **params)
+        params = Pinnacle::Internal::Types::Utils.normalize_keys(params)
+        request = Pinnacle::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "DELETE",
+          path: "calls/#{URI.encode_uri_component(params[:id].to_s)}",
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Pinnacle::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Pinnacle::Types::Call.load(response.body)
+        else
+          error_class = Pinnacle::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Replace a call's metadata. For live calls, future call events carry the updated metadata.
+      #
+      # @param request_options [Hash]
+      # @param params [Pinnacle::Calls::Types::UpdateCallParams]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :id
+      #
+      # @return [Pinnacle::Types::Call]
+      def update(request_options: {}, **params)
+        params = Pinnacle::Internal::Types::Utils.normalize_keys(params)
+        request_data = Pinnacle::Calls::Types::UpdateCallParams.new(params).to_h
+        non_body_param_names = %w[id]
+        body = request_data.except(*non_body_param_names)
+
+        request = Pinnacle::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "PATCH",
+          path: "calls/#{URI.encode_uri_component(params[:id].to_s)}",
+          body: body,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Pinnacle::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Pinnacle::Types::Call.load(response.body)
+        else
+          error_class = Pinnacle::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # List the event timeline for a call.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :id
+      # @option params [Integer, nil] :limit
+      # @option params [String, nil] :cursor
+      #
+      # @return [Pinnacle::Types::ListCallEventsResponse]
+      def list_events(request_options: {}, **params)
+        params = Pinnacle::Internal::Types::Utils.normalize_keys(params)
+        query_params = {}
+        query_params["limit"] = params[:limit] if params.key?(:limit)
+        query_params["cursor"] = params[:cursor] if params.key?(:cursor)
+
+        request = Pinnacle::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "calls/#{URI.encode_uri_component(params[:id].to_s)}/events",
+          query: query_params,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Pinnacle::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Pinnacle::Types::ListCallEventsResponse.load(response.body)
+        else
+          error_class = Pinnacle::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Mint a short-lived WebSocket token for a call. Use the returned `stream_url` to connect to Pinnacle's
+      # bidirectional voice stream.
+      #
+      # @param request_options [Hash]
+      # @param params [Pinnacle::Calls::Types::CreateStreamTokenParams]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :id
+      #
+      # @return [Pinnacle::Types::CallStreamToken]
+      def create_stream_token(request_options: {}, **params)
+        params = Pinnacle::Internal::Types::Utils.normalize_keys(params)
+        request_data = Pinnacle::Calls::Types::CreateStreamTokenParams.new(params).to_h
+        non_body_param_names = %w[id]
+        body = request_data.except(*non_body_param_names)
+
+        request = Pinnacle::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "calls/#{URI.encode_uri_component(params[:id].to_s)}/stream-token",
+          body: body,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Pinnacle::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Pinnacle::Types::CallStreamToken.load(response.body)
+        else
+          error_class = Pinnacle::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Return a short-lived signed URL for the call recording.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :id
+      # @option params [Integer, nil] :expires_in
+      #
+      # @return [Pinnacle::Types::RecordingDownload]
+      def download_recording(request_options: {}, **params)
+        params = Pinnacle::Internal::Types::Utils.normalize_keys(params)
+        query_params = {}
+        query_params["expires_in"] = params[:expires_in] if params.key?(:expires_in)
+
+        request = Pinnacle::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "calls/#{URI.encode_uri_component(params[:id].to_s)}/recording",
+          query: query_params,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Pinnacle::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Pinnacle::Types::RecordingDownload.load(response.body)
+        else
+          error_class = Pinnacle::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Delete the canonical recording and queued fragments for a terminal call.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :id
+      #
+      # @return [untyped]
+      def delete_recording(request_options: {}, **params)
+        params = Pinnacle::Internal::Types::Utils.normalize_keys(params)
+        request = Pinnacle::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "DELETE",
+          path: "calls/#{URI.encode_uri_component(params[:id].to_s)}/recording",
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Pinnacle::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        return if code.between?(200, 299)
+
+        error_class = Pinnacle::Errors::ResponseError.subclass_for_code(code)
+        raise error_class.new(response.body, code: code)
+      end
+    end
+  end
+end

data/lib/pinnacle/calls/types/calls_download_recording_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Calls
+    module Types
+      class CallsDownloadRecordingRequest < Internal::Types::Model
+        field :id, -> { String }, optional: false, nullable: false
+
+        field :expires_in, -> { Integer }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/pinnacle/calls/types/calls_list_events_request.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Calls
+    module Types
+      class CallsListEventsRequest < Internal::Types::Model
+        field :id, -> { String }, optional: false, nullable: false
+
+        field :limit, -> { Integer }, optional: true, nullable: false
+
+        field :cursor, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/pinnacle/calls/types/calls_list_request.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Calls
+    module Types
+      class CallsListRequest < Internal::Types::Model
+        field :limit, -> { Integer }, optional: true, nullable: false
+
+        field :cursor, -> { String }, optional: true, nullable: false
+
+        field :state, -> { Pinnacle::Types::CallState }, optional: true, nullable: false
+
+        field :direction, -> { Pinnacle::Types::CallDirection }, optional: true, nullable: false
+
+        field :from, -> { String }, optional: true, nullable: false
+
+        field :to, -> { String }, optional: true, nullable: false
+
+        field :created_after, -> { String }, optional: true, nullable: false
+
+        field :created_before, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/pinnacle/calls/types/create_call_params.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Calls
+    module Types
+      class CreateCallParams < Internal::Types::Model
+        field :idempotency_key, -> { String }, optional: true, nullable: false, api_name: "Idempotency-Key"
+
+        field :to, -> { String }, optional: false, nullable: false
+
+        field :from, -> { String }, optional: false, nullable: false
+
+        field :record, -> { Internal::Types::Boolean }, optional: true, nullable: false
+
+        field :metadata, -> { Internal::Types::Hash[String, String] }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/pinnacle/calls/types/create_stream_token_params.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Calls
+    module Types
+      class CreateStreamTokenParams < Internal::Types::Model
+        field :id, -> { String }, optional: false, nullable: false
+
+        field :commands_enabled, -> { Internal::Types::Boolean }, optional: true, nullable: false
+
+        field :stream_id, -> { String }, optional: true, nullable: false
+
+        field :record, -> { Internal::Types::Boolean }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/pinnacle/calls/types/update_call_params.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Calls
+    module Types
+      class UpdateCallParams < Internal::Types::Model
+        field :id, -> { String }, optional: false, nullable: false
+
+        field :metadata, -> { Internal::Types::Hash[String, String] }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/pinnacle/campaigns/dlc/client.rb

@@ -119,7 +119,7 @@ module Pinnacle
         # **To create a new campaign:** Omit `campaignId` — one will be generated automatically.
         #
         # **Before you start:** Create a [brand](/api-reference/brands/upsert) first — you'll need its `id` for the
-        # [`brand`](#request.body.brand) field.
+        # [`brand`](#request-body.applicationjson.body.brand) field.
         #
         # All fields are **required** unless specified otherwise, and will be validated when
         # [submitted](/api-reference/campaigns/10-dlc/submit).

data/lib/pinnacle/campaigns/rcs/client.rb

@@ -119,7 +119,7 @@ module Pinnacle
         # **To create a new campaign:** Omit `campaignId` — one will be generated automatically.
         #
         # **Before you start:** Create a [brand](/api-reference/brands/upsert) first — you'll need its `id` for the
-        # [`brand`](#request.body.brand) field.
+        # [`brand`](#request-body.applicationjson.body.brand) field.
         #
         # All fields are **required** unless specified otherwise, and will be validated when
         # [submitted](/api-reference/campaigns/rcs/submit).

data/lib/pinnacle/campaigns/toll_free/client.rb

@@ -119,7 +119,7 @@ module Pinnacle
         # **To create a new campaign:** Omit `campaignId` — one will be generated automatically.
         #
         # **Before you start:** Create a [brand](/api-reference/brands/upsert) first — you'll need its `id` for the
-        # [`brand`](#request.body.brand) field.
+        # [`brand`](#request-body.applicationjson.body.brand) field.
         #
         # All fields are **required** unless specified otherwise, and will be validated when
         # [submitted](/api-reference/campaigns/toll-free/submit).