openapi: 3.0.3
info:
  title: Numbers | Sinch
  description: >
    The Numbers API enables you to search for, view, and activate numbers. It's
    considered a precursor to other APIs in the Sinch product family. The
    numbers API can be used in tandem with any of our APIs that perform
    messaging or calling. Once you have activated your numbers, you can then use
    the various other APIs, such as [SMS](/docs/sms/) or [Voice](/docs/voice/),
    to assign and use those numbers.


    ## Numbers REST formats and conventions


    Let's take a brief look at some of the formats used in the REST API.


    ### JSON


    JSON (`application/json`) is the content type of both requests and responses
    if not otherwise specified.


    Requests with invalid JSON will be rejected.


    ### Null values


    Null values can be omitted in requests and will be omitted in responses. In
    some cases, explicitly setting `null` will overwrite a previously set value
    with `null`.


    ### Phone numbers


    Only phone numbers in
    [E.164](https://community.sinch.com/t5/Glossary/E-164/ta-p/7537) standard
    format are accepted by the API.


    #### Examples:


    - **US phone number:** `+13059394139`

    - **UK phone number:** `+447478727259`

    - **SE phone number:** `+46113232516`


    ## Status codes


    A summary of status codes can be found on the [HTTP status codes
    page](/docs/numbers/api-reference/error-codes/status-codes/).


    ## IP addresses for callbacks


    To successfully use callbacks with Numbers, add the following IP addresses
    to your allowlist:


    - 54.76.19.159

    - 54.78.194.39

    - 54.155.83.128


    ## New features


    New features might result in additional request and response parameters. New
    request parameters will either have a default value or be considered
    optional to retain backwards compatibility. It's highly recommended to
    ignore any unexpected parameters when reading JSON in API responses and in
    callback handlers.
  version: 1.0.3
  contact:
    name: Support
    url: https://www.sinch.com
    email: Support@sinch.com
  license:
    name: MIT
    url: https://www.sinch.com/toc
servers:
  - url: https://numbers.api.sinch.com
    description: Global API
security:
  - Basic: []
  - OAuth2.0: []
tags:
  - name: Available Number
    description: >-
      You can use the Available Number API to search for available numbers or
      activate an available number.
  - name: Active Number
    description: >-
      You can use the Active Number API to manage numbers you own. Release
      numbers from projects or list all numbers assigned to a project.
  - name: Available Regions
    description: >-
      You can use the Available Regions API to list all of the regions that have
      numbers assigned to a project.
  - name: Numbers Callbacks
    description: >-
      You can set up callback URLs to receive event notifications when your
      numbers are updated.


      When delivering events the order is not guaranteed (for example, a failed
      event scheduled for retry will not block other events that were queued).


      The client's callback handler must implement the state machine that can
      decide what to do with _unexpected_ events, for example, "old" events or
      invalid state transitions. In these cases the handler could use the API to
      GET the latest state for the resource.


      The callback handler is expected to "ingest" the event and respond with
      200 OK. The domain-specific business logic and processes should be
      executed outside of the callback request, as internal asynchronous jobs.


      To use callbacks, add the following IP addresses to your allowlist:


      - 54.76.19.159

      - 54.78.194.39

      - 54.155.83.128


      ### Secure Webhook Endpoints with HMAC


      Implementing HMAC (Hash-based Message Authentication Code) on your webhook
      endpoints will ensure the integrity of data, preventing tampering during
      transmission.

      An HMAC used in webhooks is a common approach in the industry and in a
      nutshell it is just special code that can be used to check if a message
      hasn't been tempered with during the transmission.


      We recommend to configure an HMAC secret for your project using the
      [callback
      configuration](/docs/numbers/api-reference/numbers/numbers-callbacks/updatecallbackconfiguration).
      Then, when sending the number events, the HTTP POST requests will include
      the header `X-Sinch-Signature` with the computed HMAC.


      **NOTE:** The HMAC secret is configured per project; if you are using the
      Numbers API with multiple projects, make sure you configure the HMAC
      secret in each project, and fetch it for either imported or purchased
      numbers from the dedicated endpoints.


      ### HMAC verification


      We recommend to verify the HMAC code received with every event in your
      event handler. When receiving a new event on your endpoint URL, compute
      the HMAC of the payload using the secret (configured
      [here](/docs/numbers/api-reference/numbers/numbers-callbacks/updatecallbackconfiguration))
      and compare it with one received in the `X-Sinch-Signature` header.


      **NOTE:** Compute the HMAC on the plain text value before parsing the JSON
      payload.
x-explorer-enabled: false
x-samples-languages:
  - curl
  - java
  - csharp
  - node
  - php
x-webhooks:
  EventsCallback:
    post:
      tags:
        - Numbers Callbacks
      summary: Event notification
      description: A notification of an event sent to your configured callback URL.
      operationId: ImportedNumberService_EventsCallback
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallbackPayload'
      responses:
        default:
          description: 200 OK
paths:
  /v1/projects/{projectId}/availableNumbers/{phoneNumber}:rent:
    parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/phoneNumber'
    post:
      summary: Activate a new phone number
      description: >-
        Activate a phone number to use with SMS products, Voice products, or
        both.


        You'll use `smsConfiguration` to setup your number for SMS and
        `voiceConfiguration` for Voice. To setup for both, add both objects. See
        the dropdown menu (just under language selection) for code samples.


        Note: You cannot add both objects if you only need to configure one
        object. For example, if you only need to configure `smsConfiguration`
        for SMS messaging, do not add the `voiceConfiguration` object or it will
        result in an error.
      operationId: NumberService_RentNumber
      requestBody:
        $ref: '#/components/requestBodies/RentNumberRequest'
      responses:
        '200':
          $ref: '#/components/responses/ActiveNumberResponse'
        '400':
          description: 400 Invalid Argument error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument'
        '403':
          $ref: '#/components/responses/PermissionDenied'
        '404':
          description: 404 Not Found error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: 500 Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      tags:
        - Available Number
      x-codeSamples:
        - lang: Java
          source: >
            /**
             * Sinch Java Snippet
             *
             * <p>This snippet is available at https://github.com/sinch/sinch-sdk-java-snippets
             *
             * <p>See https://github.com/sinch/sinch-sdk-java-snippets/blob/main/README.md for details
             */
            package numbers;


            import com.sinch.sdk.SinchClient;

            import com.sinch.sdk.domains.numbers.api.v1.NumbersService;

            import com.sinch.sdk.domains.numbers.models.v1.ActiveNumber;

            import com.sinch.sdk.domains.numbers.models.v1.SmsConfiguration;

            import
            com.sinch.sdk.domains.numbers.models.v1.request.AvailableNumberRentRequest;

            import com.sinch.sdk.models.Configuration;

            import java.util.logging.Logger;

            import utils.Settings;


            public class Rent {

              private static final Logger LOGGER = Logger.getLogger(Rent.class.getName());

              public static void main(String[] args) {

                String projectId = Settings.getProjectId().orElse("MY_PROJECT_ID");
                String keyId = Settings.getKeyId().orElse("MY_KEY_ID");
                String keySecret = Settings.getKeySecret().orElse("MY_KEY_SECRET");

                String servicePlanIdToAssociateWithTheNumber =
                    Settings.getServicePlanId().orElse("MY_SERVICE_PLAN_ID");

                // Available numbers list can be retrieved by using list() function from available service, see
                // the SearchAvailableSnippet or
                // https://developers.sinch.com/docs/numbers/getting-started/java-sdk/searchavailable
                String phoneNumberToBeRented = "AVAILABLE_PHONE_NUMBER_TO_BE_RENTED";

                Configuration configuration =
                    Configuration.builder()
                        .setProjectId(projectId)
                        .setKeyId(keyId)
                        .setKeySecret(keySecret)
                        .build();

                SinchClient client = new SinchClient(configuration);

                NumbersService numbersService = client.numbers().v1();

                SmsConfiguration smsConfiguration =
                    SmsConfiguration.builder().setServicePlanId(servicePlanIdToAssociateWithTheNumber).build();

                AvailableNumberRentRequest parameters =
                    AvailableNumberRentRequest.builder().setSmsConfiguration(smsConfiguration).build();

                ActiveNumber response = numbersService.rent(phoneNumberToBeRented, parameters);

                LOGGER.info(String.format("Rented number: %s", response));
              }
            }
  /v1/projects/{projectId}/availableNumbers:rentAny:
    parameters:
      - $ref: '#/components/parameters/projectId'
    post:
      tags:
        - Available Number
      summary: Rent any number that matches the criteria
      description: >-
        Activates a phone number that matches the search criteria provided in
        the request. Currently the rentAny operation works only for US LOCAL
        numbers
      operationId: NumberService_RentAnyNumber
      requestBody:
        description: The request to search and rent a number that matches the criteria.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RentAnyNumberRequest'
            examples:
              activateSMSNumber:
                $ref: '#/components/examples/SearchActivateSMSNumber'
        required: true
      responses:
        '200':
          description: >-
            A successful response, or an
            [error](https://developers.sinch.com/docs/numbers/api-reference/error-codes/status-codes).
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveNumberResponse'
        '400':
          description: 400 Invalid Argument error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument'
        '403':
          $ref: '#/components/responses/PermissionDenied'
        '404':
          description: 404 Not Found error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: 500 Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      deprecated: false
      x-codeSamples:
        - lang: Java
          source: >
            /**
             * Sinch Java Snippet
             *
             * <p>This snippet is available at https://github.com/sinch/sinch-sdk-java-snippets
             *
             * <p>See https://github.com/sinch/sinch-sdk-java-snippets/blob/main/README.md for details
             */
            package numbers;


            import com.sinch.sdk.SinchClient;

            import com.sinch.sdk.domains.numbers.api.v1.NumbersService;

            import com.sinch.sdk.domains.numbers.models.v1.ActiveNumber;

            import com.sinch.sdk.domains.numbers.models.v1.NumberType;

            import com.sinch.sdk.domains.numbers.models.v1.SmsConfiguration;

            import
            com.sinch.sdk.domains.numbers.models.v1.request.AvailableNumberRentAnyRequest;

            import com.sinch.sdk.models.Configuration;

            import java.util.logging.Logger;

            import utils.Settings;


            public class RentAny {

              private static final Logger LOGGER = Logger.getLogger(RentAny.class.getName());

              public static void main(String[] args) {

                String projectId = Settings.getProjectId().orElse("MY_PROJECT_ID");
                String keyId = Settings.getKeyId().orElse("MY_KEY_ID");
                String keySecret = Settings.getKeySecret().orElse("MY_KEY_SECRET");

                String servicePlanIdToAssociateWithTheNumber =
                    Settings.getServicePlanId().orElse("MY_SERVICE_PLAN_ID");

                // ISO 3166-1 alpha-2 country code of the phone number. e.g. "US", "GB", "SE"...
                // See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for details
                String regionCode = "MY_REGION_CODE";

                NumberType numberType = NumberType.LOCAL;

                Configuration configuration =
                    Configuration.builder()
                        .setProjectId(projectId)
                        .setKeyId(keyId)
                        .setKeySecret(keySecret)
                        .build();

                SinchClient client = new SinchClient(configuration);

                NumbersService numbersService = client.numbers().v1();

                SmsConfiguration smsConfiguration =
                    SmsConfiguration.builder().setServicePlanId(servicePlanIdToAssociateWithTheNumber).build();

                AvailableNumberRentAnyRequest parameters =
                    AvailableNumberRentAnyRequest.builder()
                        .setType(numberType)
                        .setRegionCode(regionCode)
                        .setSmsConfiguration(smsConfiguration)
                        .build();

                ActiveNumber response = numbersService.rentAny(parameters);

                LOGGER.info(String.format("Rented number: %s", response));
              }
            }
  /v1/projects/{projectId}/activeNumbers:
    parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/regionCode'
      - $ref: '#/components/parameters/numberPattern.pattern'
      - $ref: '#/components/parameters/numberPattern.searchPattern'
      - $ref: '#/components/parameters/type'
      - $ref: '#/components/parameters/capability'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/pageToken'
      - $ref: '#/components/parameters/orderBy'
    get:
      summary: Lists active numbers for a project
      description: Lists all active numbers for a project.
      operationId: NumberService_ListActiveNumbers
      responses:
        '200':
          $ref: '#/components/responses/ListActiveNumbersResponse'
        '400':
          description: 400 Invalid Argument error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument'
        '403':
          $ref: '#/components/responses/PermissionDenied'
        '404':
          description: 404 Not Found error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: 500 Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      tags:
        - Active Number
      x-codeSamples:
        - lang: Java
          source: >
            /**
             * Sinch Java Snippet
             *
             * <p>This snippet is available at https://github.com/sinch/sinch-sdk-java-snippets
             *
             * <p>See https://github.com/sinch/sinch-sdk-java-snippets/blob/main/README.md for details
             */
            package numbers;


            import com.sinch.sdk.SinchClient;

            import com.sinch.sdk.domains.numbers.api.v1.NumbersService;

            import com.sinch.sdk.domains.numbers.models.v1.NumberType;

            import
            com.sinch.sdk.domains.numbers.models.v1.request.ActiveNumbersListQueryParameters;

            import
            com.sinch.sdk.domains.numbers.models.v1.response.ActiveNumberListResponse;

            import com.sinch.sdk.models.Configuration;

            import java.util.logging.Logger;

            import utils.Settings;


            public class List {

              private static final Logger LOGGER = Logger.getLogger(List.class.getName());

              public static void main(String[] args) {

                String projectId = Settings.getProjectId().orElse("MY_PROJECT_ID");
                String keyId = Settings.getKeyId().orElse("MY_KEY_ID");
                String keySecret = Settings.getKeySecret().orElse("MY_KEY_SECRET");

                Configuration configuration =
                    Configuration.builder()
                        .setProjectId(projectId)
                        .setKeyId(keyId)
                        .setKeySecret(keySecret)
                        .build();

                SinchClient client = new SinchClient(configuration);

                NumbersService numbersService = client.numbers().v1();

                LOGGER.info("Listing active numbers");

                ActiveNumberListResponse response =
                    numbersService.list(
                        ActiveNumbersListQueryParameters.builder()
                            .setRegionCode("US")
                            .setType(NumberType.LOCAL)
                            .build());

                LOGGER.info("Response");

                response
                    .iterator()
                    .forEachRemaining(f -> LOGGER.info(String.format("%s: %s", f.getPhoneNumber(), f)));
              }
            }
  /v1/projects/{projectId}/activeNumbers/{phoneNumber}:
    parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/phoneNumber'
    patch:
      summary: Update an active phone number
      description: >-
        Update an active phone number. You can perform the following updates:


        * Update the name that displays for a customer by modifying the
        `displayName` parameter.

        * Unlink the number from an SMS service or campaign by updating the
        `smsConfiguration` configuration object. To unlink a number, submit the
        request with an empty string (`””`) in the service plan ID or campaign
        ID fields.

        * Before linking a number to a new service or campaign, it must be
        unlinked from any existing service or campaign. Then, link the number to
        a new SMS service or campaign by updating the service plan ID or
        campaign ID with the new desired value.

        * Update the Voice app to which the number is assigned by using the
        voiceConfiguration object.


        You can update both SMS and Voice in the same object by including both
        configuration objects. If you only need to update either Voice or SMS,
        simply omit the other object. If you pass an empty configuration object,
        the request will fail.
      operationId: NumberService_UpdateActiveNumber
      requestBody:
        $ref: '#/components/requestBodies/ActiveNumberRequest'
      responses:
        '200':
          $ref: '#/components/responses/ActiveNumberResponse'
        '400':
          description: 400 Invalid Argument error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument'
        '403':
          $ref: '#/components/responses/PermissionDenied'
        '404':
          description: 404 Not Found error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: 500 Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      tags:
        - Active Number
      x-codeSamples:
        - lang: Java
          source: >
            /**
             * Sinch Java Snippet
             *
             * <p>This snippet is available at https://github.com/sinch/sinch-sdk-java-snippets
             *
             * <p>See https://github.com/sinch/sinch-sdk-java-snippets/blob/main/README.md for details
             */
            package numbers;


            import com.sinch.sdk.SinchClient;

            import com.sinch.sdk.domains.numbers.api.v1.NumbersService;

            import com.sinch.sdk.domains.numbers.models.v1.ActiveNumber;

            import
            com.sinch.sdk.domains.numbers.models.v1.request.ActiveNumberUpdateRequest;

            import com.sinch.sdk.models.Configuration;

            import java.util.logging.Logger;

            import utils.Settings;


            public class Update {

              private static final Logger LOGGER = Logger.getLogger(Update.class.getName());

              public static void main(String[] args) {

                String projectId = Settings.getProjectId().orElse("MY_PROJECT_ID");
                String keyId = Settings.getKeyId().orElse("MY_KEY_ID");
                String keySecret = Settings.getKeySecret().orElse("MY_KEY_SECRET");

                String phoneNumber = Settings.getPhoneNumber().orElse("MY_SINCH_PHONE_NUMBER");

                String displayName = "Updated with Sinch Java SDK";

                Configuration configuration =
                    Configuration.builder()
                        .setProjectId(projectId)
                        .setKeyId(keyId)
                        .setKeySecret(keySecret)
                        .build();

                SinchClient client = new SinchClient(configuration);

                NumbersService numbersService = client.numbers().v1();

                ActiveNumberUpdateRequest updateRequest =
                    ActiveNumberUpdateRequest.builder().setDisplayName(displayName).build();

                ActiveNumber response = numbersService.update(phoneNumber, updateRequest);

                LOGGER.info(String.format("Updated number: %s", response));
              }
            }
    get:
      summary: Retrieve an active phone number
      description: Retrieve a specific active phone number.
      operationId: NumberService_GetActiveNumber
      responses:
        '200':
          $ref: '#/components/responses/ActiveNumberResponse'
        '400':
          description: 400 Invalid Argument error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument'
        '404':
          description: 404 Not Found error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: 500 Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      tags:
        - Active Number
      x-codeSamples:
        - lang: Java
          source: |
            /**
             * Sinch Java Snippet
             *
             * <p>This snippet is available at https://github.com/sinch/sinch-sdk-java-snippets
             *
             * <p>See https://github.com/sinch/sinch-sdk-java-snippets/blob/main/README.md for details
             */
            package numbers;

            import com.sinch.sdk.SinchClient;
            import com.sinch.sdk.domains.numbers.api.v1.NumbersService;
            import com.sinch.sdk.domains.numbers.models.v1.ActiveNumber;
            import com.sinch.sdk.models.Configuration;
            import java.util.logging.Logger;
            import utils.Settings;

            public class Get {

              private static final Logger LOGGER = Logger.getLogger(Get.class.getName());

              public static void main(String[] args) {

                String projectId = Settings.getProjectId().orElse("MY_PROJECT_ID");
                String keyId = Settings.getKeyId().orElse("MY_KEY_ID");
                String keySecret = Settings.getKeySecret().orElse("MY_KEY_SECRET");

                String phoneNumber = Settings.getPhoneNumber().orElse("MY_SINCH_PHONE_NUMBER");

                Configuration configuration =
                    Configuration.builder()
                        .setProjectId(projectId)
                        .setKeyId(keyId)
                        .setKeySecret(keySecret)
                        .build();

                SinchClient client = new SinchClient(configuration);

                NumbersService numbersService = client.numbers().v1();

                LOGGER.info("Get for: " + phoneNumber);
                ActiveNumber value = numbersService.get(phoneNumber);

                LOGGER.info("Response: " + value);
              }
            }
  /v1/projects/{projectId}/activeNumbers/{phoneNumber}:release:
    parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/phoneNumber'
    post:
      summary: Release an active number from the project
      description: >-
        With this endpoint, you can cancel your subscription for a specific
        phone number.
      operationId: NumberService_ReleaseNumber
      responses:
        '200':
          $ref: '#/components/responses/ActiveNumberResponse'
        '400':
          description: 400 Invalid Argument error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument'
        '403':
          $ref: '#/components/responses/PermissionDenied'
        '404':
          description: 404 Not Found error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: 500 Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      tags:
        - Active Number
      x-codeSamples:
        - lang: Java
          source: |
            /**
             * Sinch Java Snippet
             *
             * <p>This snippet is available at https://github.com/sinch/sinch-sdk-java-snippets
             *
             * <p>See https://github.com/sinch/sinch-sdk-java-snippets/blob/main/README.md for details
             */
            package numbers;

            import com.sinch.sdk.SinchClient;
            import com.sinch.sdk.domains.numbers.api.v1.NumbersService;
            import com.sinch.sdk.domains.numbers.models.v1.ActiveNumber;
            import com.sinch.sdk.models.Configuration;
            import java.util.logging.Logger;
            import utils.Settings;

            public class Release {

              private static final Logger LOGGER = Logger.getLogger(Release.class.getName());

              public static void main(String[] args) {

                String projectId = Settings.getProjectId().orElse("MY_PROJECT_ID");
                String keyId = Settings.getKeyId().orElse("MY_KEY_ID");
                String keySecret = Settings.getKeySecret().orElse("MY_KEY_SECRET");

                String phoneNumber = Settings.getPhoneNumber().orElse("MY_SINCH_PHONE_NUMBER");

                Configuration configuration =
                    Configuration.builder()
                        .setProjectId(projectId)
                        .setKeyId(keyId)
                        .setKeySecret(keySecret)
                        .build();

                SinchClient client = new SinchClient(configuration);

                NumbersService numbersService = client.numbers().v1();

                LOGGER.info("Release for: " + phoneNumber);

                ActiveNumber value = numbersService.release(phoneNumber);

                LOGGER.info("Response: " + value);
              }
            }
  /v1/projects/{projectId}/availableNumbers:
    parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/numberPattern.pattern'
      - $ref: '#/components/parameters/numberPattern.searchPattern'
      - $ref: '#/components/parameters/regionCode'
      - $ref: '#/components/parameters/type'
      - $ref: '#/components/parameters/capabilities'
      - name: size
        description: Optional. The maximum number of items to return.
        in: query
        required: false
        schema:
          type: integer
          format: int32
        example: 3
    get:
      summary: Search for available phone numbers
      description: >-
        Search for available phone numbers that are available for you to
        activate. You can filter by any property on the available number
        resource.


        When searching, indicate the `capability` of the number in the array as
        `SMS` and/or `VOICE`. To search for a number capable of both, list both
        `SMS` and `VOICE`.
      operationId: NumberService_ListAvailableNumbers
      responses:
        '200':
          $ref: '#/components/responses/ListAvailableNumbersResponse'
        '400':
          description: 400 Invalid Argument error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument'
        '403':
          $ref: '#/components/responses/PermissionDenied'
        '404':
          description: 404 Not Found error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: 500 Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      tags:
        - Available Number
      x-codeSamples:
        - lang: Java
          source: >
            /**
             * Sinch Java Snippet
             *
             * <p>This snippet is available at https://github.com/sinch/sinch-sdk-java-snippets
             *
             * <p>See https://github.com/sinch/sinch-sdk-java-snippets/blob/main/README.md for details
             */
            package numbers;


            import com.sinch.sdk.SinchClient;

            import com.sinch.sdk.domains.numbers.api.v1.NumbersService;

            import com.sinch.sdk.domains.numbers.models.v1.NumberType;

            import
            com.sinch.sdk.domains.numbers.models.v1.request.AvailableNumbersListQueryParameters;

            import
            com.sinch.sdk.domains.numbers.models.v1.response.AvailableNumberListResponse;

            import com.sinch.sdk.models.Configuration;

            import java.util.logging.Logger;

            import utils.Settings;


            public class SearchForAvailableNumbers {

              private static final Logger LOGGER = Logger.getLogger(SearchForAvailableNumbers.class.getName());

              public static void main(String[] args) {

                String projectId = Settings.getProjectId().orElse("MY_PROJECT_ID");
                String keyId = Settings.getKeyId().orElse("MY_KEY_ID");
                String keySecret = Settings.getKeySecret().orElse("MY_KEY_SECRET");

                // ISO 3166-1 alpha-2 country code of the phone number. e.g. "US", "GB", "SE"...
                // See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for details
                String regionCode = "MY_REGION_CODE";
                NumberType type = NumberType.LOCAL;

                Configuration configuration =
                    Configuration.builder()
                        .setProjectId(projectId)
                        .setKeyId(keyId)
                        .setKeySecret(keySecret)
                        .build();

                SinchClient client = new SinchClient(configuration);

                NumbersService numbersService = client.numbers().v1();

                AvailableNumbersListQueryParameters parameters =
                    AvailableNumbersListQueryParameters.builder()
                        .setRegionCode(regionCode)
                        .setType(type)
                        .build();

                LOGGER.info("Looking for available numbers");

                AvailableNumberListResponse response = numbersService.searchForAvailableNumbers(parameters);

                response
                    .iterator()
                    .forEachRemaining(
                        number -> LOGGER.info(String.format("Available number details: %s", number)));
              }
            }
  /v1/projects/{projectId}/availableNumbers/{phoneNumber}:
    parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/phoneNumber'
    get:
      summary: Search for a specific phone number
      description: >-
        This endpoint allows you to enter a specific phone number to check if
        it's available for use. A 200 response will return the number's
        capability, setup costs, monthly costs and if supporting documentation
        is required.
      operationId: NumberService_GetAvailableNumber
      responses:
        '200':
          $ref: '#/components/responses/AvailableNumberResponse'
        '400':
          description: 400 Invalid Argument error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument'
        '403':
          $ref: '#/components/responses/PermissionDenied'
        '404':
          description: 404 Not Found error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: 500 Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      tags:
        - Available Number
      x-codeSamples:
        - lang: Java
          source: >
            /**
             * Sinch Java Snippet
             *
             * <p>This snippet is available at https://github.com/sinch/sinch-sdk-java-snippets
             *
             * <p>See https://github.com/sinch/sinch-sdk-java-snippets/blob/main/README.md for details
             */
            package numbers;


            import com.sinch.sdk.SinchClient;

            import com.sinch.sdk.domains.numbers.api.v1.NumbersService;

            import
            com.sinch.sdk.domains.numbers.models.v1.response.AvailableNumber;

            import com.sinch.sdk.models.Configuration;

            import java.util.logging.Logger;

            import utils.Settings;


            public class CheckAvailability {

              private static final Logger LOGGER = Logger.getLogger(CheckAvailability.class.getName());

              public static void main(String[] args) {

                String projectId = Settings.getProjectId().orElse("MY_PROJECT_ID");
                String keyId = Settings.getKeyId().orElse("MY_KEY_ID");
                String keySecret = Settings.getKeySecret().orElse("MY_KEY_SECRET");

                String phoneNumber = "A_PHONE_NUMBER_TO_CHECK";

                Configuration configuration =
                    Configuration.builder()
                        .setProjectId(projectId)
                        .setKeyId(keyId)
                        .setKeySecret(keySecret)
                        .build();

                SinchClient client = new SinchClient(configuration);

                NumbersService numbersService = client.numbers().v1();

                LOGGER.info("CheckAvailability for: " + phoneNumber);

                AvailableNumber value = numbersService.checkAvailability(phoneNumber);

                LOGGER.info("Response: " + value);
              }
            }
  /v1/projects/{projectId}/availableRegions:
    parameters:
      - $ref: '#/components/parameters/projectId'
      - name: types
        description: >-
          Only return regions for which numbers are provided with the given
          types: `MOBILE`, `LOCAL` or `TOLL_FREE`.

            - MOBILE: Numbers that belong to a specific range.
            - LOCAL: Numbers that are assigned to a specific geographic region.
            - TOLL_FREE: Number that are free of charge for the calling party but billed for all arriving calls.

          If you want to see all results, do not add the `types` query
          parameter.
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/NumberType'
    get:
      summary: List available regions
      description: Lists all regions for numbers provided for the project ID.
      operationId: NumberService_ListAvailableRegions
      responses:
        '200':
          $ref: '#/components/responses/ListAvailableRegionsResponse'
        '400':
          description: 400 Invalid Argument error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument'
        '403':
          $ref: '#/components/responses/PermissionDenied'
        '404':
          description: 404 Not Found error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: 500 Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      tags:
        - Available Regions
      x-codeSamples:
        - lang: Java
          source: >
            /**
             * Sinch Java Snippet
             *
             * <p>This snippet is available at https://github.com/sinch/sinch-sdk-java-snippets
             *
             * <p>See https://github.com/sinch/sinch-sdk-java-snippets/blob/main/README.md for details
             */
            package numbers.regions;


            import com.sinch.sdk.SinchClient;

            import com.sinch.sdk.domains.numbers.api.v1.AvailableRegionsService;

            import
            com.sinch.sdk.domains.numbers.models.v1.regions.available.response.AvailableRegionListResponse;

            import com.sinch.sdk.models.Configuration;

            import java.util.logging.Logger;

            import utils.Settings;


            public class List {

              private static final Logger LOGGER = Logger.getLogger(List.class.getName());

              public static void main(String[] args) {

                String projectId = Settings.getProjectId().orElse("MY_PROJECT_ID");
                String keyId = Settings.getKeyId().orElse("MY_KEY_ID");
                String keySecret = Settings.getKeySecret().orElse("MY_KEY_SECRET");

                Configuration configuration =
                    Configuration.builder()
                        .setProjectId(projectId)
                        .setKeyId(keyId)
                        .setKeySecret(keySecret)
                        .build();

                SinchClient client = new SinchClient(configuration);

                AvailableRegionsService availableRegionsService = client.numbers().v1().regions();

                LOGGER.info("List");

                AvailableRegionListResponse response = availableRegionsService.list();

                LOGGER.info("Available regions:");

                response.iterator().forEachRemaining(item -> LOGGER.info(String.format("- %s", item)));
              }
            }
  /v1/projects/{projectId}/callbackConfiguration:
    get:
      summary: Get callbacks configuration
      description: Returns the callbacks configuration for the specified project
      operationId: GetCallbackConfiguration
      responses:
        '200':
          description: Callbacks configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallbackConfiguration'
        '400':
          description: 400 Invalid Argument error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument'
        '403':
          $ref: '#/components/responses/PermissionDenied'
        '404':
          description: 404 Not Found error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: 500 Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      parameters:
        - $ref: '#/components/parameters/projectId'
      tags:
        - Numbers Callbacks
      x-codeSamples:
        - lang: Java
          source: >
            /**
             * Sinch Java Snippet
             *
             * <p>This snippet is available at https://github.com/sinch/sinch-sdk-java-snippets
             *
             * <p>See https://github.com/sinch/sinch-sdk-java-snippets/blob/main/README.md for details
             */
            package numbers.callback;


            import com.sinch.sdk.SinchClient;

            import
            com.sinch.sdk.domains.numbers.api.v1.CallbackConfigurationService;

            import
            com.sinch.sdk.domains.numbers.models.v1.callbacks.response.CallbackConfigurationResponse;

            import com.sinch.sdk.models.Configuration;

            import java.util.logging.Logger;

            import utils.Settings;


            public class Get {

              private static final Logger LOGGER = Logger.getLogger(Get.class.getName());

              public static void main(String[] args) {

                String projectId = Settings.getProjectId().orElse("MY_PROJECT_ID");
                String keyId = Settings.getKeyId().orElse("MY_KEY_ID");
                String keySecret = Settings.getKeySecret().orElse("MY_KEY_SECRET");

                Configuration configuration =
                    Configuration.builder()
                        .setProjectId(projectId)
                        .setKeyId(keyId)
                        .setKeySecret(keySecret)
                        .build();

                SinchClient client = new SinchClient(configuration);

                CallbackConfigurationService callbackConfigurationService = client.numbers().v1().callback();

                LOGGER.info("Get");

                CallbackConfigurationResponse value = callbackConfigurationService.get();

                LOGGER.info("Response :" + value);
              }
            }
    patch:
      summary: Update callback configuration
      description: Updates the callbacks configuration for the specified project
      operationId: UpdateCallbackConfiguration
      requestBody:
        description: The callback configuration details to be updated.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallbackConfigurationUpdate'
      responses:
        '200':
          description: Callback configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallbackConfiguration'
        '400':
          description: 400 Invalid Argument error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument'
        '403':
          $ref: '#/components/responses/PermissionDenied'
        '404':
          description: 404 Not Found error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: 500 Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      parameters:
        - $ref: '#/components/parameters/projectId'
      tags:
        - Numbers Callbacks
      x-codeSamples:
        - lang: Java
          source: >
            /**
             * Sinch Java Snippet
             *
             * <p>This snippet is available at https://github.com/sinch/sinch-sdk-java-snippets
             *
             * <p>See https://github.com/sinch/sinch-sdk-java-snippets/blob/main/README.md for details
             */
            package numbers.callback;


            import com.sinch.sdk.SinchClient;

            import
            com.sinch.sdk.domains.numbers.api.v1.CallbackConfigurationService;

            import
            com.sinch.sdk.domains.numbers.models.v1.callbacks.request.CallbackConfigurationUpdateRequest;

            import
            com.sinch.sdk.domains.numbers.models.v1.callbacks.response.CallbackConfigurationResponse;

            import com.sinch.sdk.models.Configuration;

            import java.util.logging.Logger;

            import utils.Settings;


            public class Update {

              private static final Logger LOGGER = Logger.getLogger(Update.class.getName());

              public static void main(String[] args) {

                String projectId = Settings.getProjectId().orElse("MY_PROJECT_ID");
                String keyId = Settings.getKeyId().orElse("MY_KEY_ID");
                String keySecret = Settings.getKeySecret().orElse("MY_KEY_SECRET");

                String hmac = "NEW_HMAC_SECRET";

                Configuration configuration =
                    Configuration.builder()
                        .setProjectId(projectId)
                        .setKeyId(keyId)
                        .setKeySecret(keySecret)
                        .build();

                SinchClient client = new SinchClient(configuration);

                CallbackConfigurationService callbackConfigurationService = client.numbers().v1().callback();

                LOGGER.info("Update callback HMAC secret");

                CallbackConfigurationUpdateRequest parameters =
                    CallbackConfigurationUpdateRequest.builder().setHmacSecret(hmac).build();

                CallbackConfigurationResponse value = callbackConfigurationService.update(parameters);

                LOGGER.info("Response :" + value);
              }
            }
  /v1/projects/{projectId}/activeNumbers/{phoneNumber}/emergencyAddress:
    parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/phoneNumber'
    get:
      summary: Get the emergency address for a number
      description: >-
        With this endpoint, you can retrieve the emergency address associated
        with this number.
      operationId: NumberService_GetEmergencyAddress
      responses:
        '200':
          $ref: '#/components/responses/EmergencyAddressResponse'
        '400':
          description: 400 Invalid Argument error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument'
        '403':
          $ref: '#/components/responses/PermissionDenied'
        '404':
          description: 404 Not Found error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: 500 Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      tags:
        - Active Number
      x-codeSamples:
        - lang: Java
          source: |
            /**
             * Sinch Java Snippet
             *
             * <p>This snippet is available at https://github.com/sinch/sinch-sdk-java-snippets
             *
             * <p>See https://github.com/sinch/sinch-sdk-java-snippets/blob/main/README.md for details
             */
            package numbers;

            import com.sinch.sdk.SinchClient;
            import com.sinch.sdk.domains.numbers.api.v1.NumbersService;
            import com.sinch.sdk.domains.numbers.models.v1.EmergencyAddress;
            import com.sinch.sdk.models.Configuration;
            import java.util.logging.Logger;
            import utils.Settings;

            public class GetEmergencyAddress {
              private static final Logger LOGGER = Logger.getLogger(GetEmergencyAddress.class.getName());

              public static void main(String[] args) {

                String projectId = Settings.getProjectId().orElse("MY_PROJECT_ID");
                String keyId = Settings.getKeyId().orElse("MY_KEY_ID");
                String keySecret = Settings.getKeySecret().orElse("MY_KEY_SECRET");

                String phoneNumber = Settings.getPhoneNumber().orElse("MY_SINCH_PHONE_NUMBER");

                Configuration configuration =
                    Configuration.builder()
                        .setProjectId(projectId)
                        .setKeyId(keyId)
                        .setKeySecret(keySecret)
                        .build();

                SinchClient client = new SinchClient(configuration);

                NumbersService numbersService = client.numbers().v1();

                LOGGER.info("Get EmergencyAddress for: " + phoneNumber);

                EmergencyAddress response = numbersService.getEmergencyAddress(phoneNumber);

                LOGGER.info("Response: " + response);
              }
            }
  /v1/projects/{projectId}/activeNumbers/{phoneNumber}/emergencyAddress:provision:
    parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/phoneNumber'
    post:
      summary: Add a emergency address for a number
      description: >-
        With this endpoint, you can provision an emergency address associated
        with this number.
      operationId: NumberService_ProvisionEmergencyAddress
      requestBody:
        $ref: '#/components/requestBodies/ProvisionEmergencyAddressRequest'
      responses:
        '200':
          $ref: '#/components/responses/EmergencyAddressResponse'
        '400':
          description: 400 Invalid Argument error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument'
        '403':
          $ref: '#/components/responses/PermissionDenied'
        '404':
          description: 404 Not Found error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: 500 Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      tags:
        - Active Number
      x-codeSamples:
        - lang: Java
          source: >
            /**
             * Sinch Java Snippet
             *
             * <p>This snippet is available at https://github.com/sinch/sinch-sdk-java-snippets
             *
             * <p>See https://github.com/sinch/sinch-sdk-java-snippets/blob/main/README.md for details
             */
            package numbers;


            import com.sinch.sdk.SinchClient;

            import com.sinch.sdk.domains.numbers.api.v1.NumbersService;

            import com.sinch.sdk.domains.numbers.models.v1.EmergencyAddress;

            import
            com.sinch.sdk.domains.numbers.models.v1.request.EmergencyAddressRequest;

            import com.sinch.sdk.models.Configuration;

            import java.util.logging.Logger;

            import utils.Settings;


            public class ProvisionEmergencyAddress {

              private static final Logger LOGGER = Logger.getLogger(ProvisionEmergencyAddress.class.getName());

              public static void main(String[] args) {

                String projectId = Settings.getProjectId().orElse("MY_PROJECT_ID");
                String keyId = Settings.getKeyId().orElse("MY_KEY_ID");
                String keySecret = Settings.getKeySecret().orElse("MY_KEY_SECRET");

                String phoneNumber = Settings.getPhoneNumber().orElse("MY_SINCH_PHONE_NUMBER");

                Configuration configuration =
                    Configuration.builder()
                        .setProjectId(projectId)
                        .setKeyId(keyId)
                        .setKeySecret(keySecret)
                        .build();

                SinchClient client = new SinchClient(configuration);

                NumbersService numbersService = client.numbers().v1();

                LOGGER.info("Provisioning EmergencyAddress for: " + phoneNumber);

                EmergencyAddress emergencyAddress =
                    EmergencyAddress.builder()
                        .setStreetNumber("3500")
                        .setStreetInfo("Lenox Rd NE")
                        .setCity("Atlanta")
                        .setState("GA")
                        .setPostalCode("30326")
                        .build();

                EmergencyAddressRequest request =
                    EmergencyAddressRequest.builder()
                        .setDisplayName("Emergency Address Display Name")
                        .setAddress(emergencyAddress)
                        .build();
                EmergencyAddress value = numbersService.provisionEmergencyAddress(phoneNumber, request);

                LOGGER.info("Response: " + value);
              }
            }
  /v1/projects/{projectId}/activeNumbers/{phoneNumber}/emergencyAddress:deprovision:
    parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/phoneNumber'
    post:
      summary: Remove the emergency address for a number.
      description: >-
        With this endpoint, you can deprovision the emergency address associated
        with this number.
      operationId: NumberService_DeprovisionEmergencyAddress
      responses:
        '200':
          description: >-
            A successful response, or an
            [error](/docs/numbers/api-reference/error-codes/status-codes/)
        '400':
          description: 400 Invalid Argument error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument'
        '403':
          $ref: '#/components/responses/PermissionDenied'
        '404':
          description: 404 Not Found error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: 500 Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      tags:
        - Active Number
      x-codeSamples:
        - lang: Java
          source: |
            /**
             * Sinch Java Snippet
             *
             * <p>This snippet is available at https://github.com/sinch/sinch-sdk-java-snippets
             *
             * <p>See https://github.com/sinch/sinch-sdk-java-snippets/blob/main/README.md for details
             */
            package numbers;

            import com.sinch.sdk.SinchClient;
            import com.sinch.sdk.domains.numbers.api.v1.NumbersService;
            import com.sinch.sdk.models.Configuration;
            import java.util.logging.Logger;
            import utils.Settings;

            public class DeprovisionEmergencyAddress {
              private static final Logger LOGGER =
                  Logger.getLogger(DeprovisionEmergencyAddress.class.getName());

              public static void main(String[] args) {

                String projectId = Settings.getProjectId().orElse("MY_PROJECT_ID");
                String keyId = Settings.getKeyId().orElse("MY_KEY_ID");
                String keySecret = Settings.getKeySecret().orElse("MY_KEY_SECRET");

                String phoneNumber = Settings.getPhoneNumber().orElse("MY_SINCH_PHONE_NUMBER");

                Configuration configuration =
                    Configuration.builder()
                        .setProjectId(projectId)
                        .setKeyId(keyId)
                        .setKeySecret(keySecret)
                        .build();

                SinchClient client = new SinchClient(configuration);

                NumbersService numbersService = client.numbers().v1();

                LOGGER.info("De-provisioning EmergencyAddress for: " + phoneNumber);

                numbersService.deprovisionEmergencyAddress(phoneNumber);
              }
            }
  /v1/projects/{projectId}/activeNumbers/{phoneNumber}/emergencyAddress:validate:
    parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/phoneNumber'
    post:
      summary: Validate the emergency address for a number.
      description: >-
        With this endpoint, you can validate the emergency address associated
        with this number.
      operationId: NumberService_ValidateEmergencyAddress
      requestBody:
        $ref: '#/components/requestBodies/ValidateEmergencyAddressRequest'
      responses:
        '200':
          description: >-
            A successful response, or an
            [error](/docs/numbers/api-reference/error-codes/status-codes/)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateAddressResponse'
              examples:
                perfectMatch:
                  $ref: '#/components/examples/perfectMatch'
                nearMatch:
                  $ref: '#/components/examples/nearMatch'
                noMatch:
                  $ref: '#/components/examples/noMatch'
        '400':
          description: 400 Invalid Argument error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidArgument'
        '404':
          description: 404 Not Found error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: 500 Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      tags:
        - Active Number
      x-codeSamples:
        - lang: Java
          source: >
            /**
             * Sinch Java Snippet
             *
             * <p>This snippet is available at https://github.com/sinch/sinch-sdk-java-snippets
             *
             * <p>See https://github.com/sinch/sinch-sdk-java-snippets/blob/main/README.md for details
             */
            package numbers;


            import com.sinch.sdk.SinchClient;

            import com.sinch.sdk.domains.numbers.api.v1.NumbersService;

            import com.sinch.sdk.domains.numbers.models.v1.EmergencyAddress;

            import
            com.sinch.sdk.domains.numbers.models.v1.request.EmergencyAddressRequest;

            import
            com.sinch.sdk.domains.numbers.models.v1.response.ValidateAddressResponse;

            import com.sinch.sdk.models.Configuration;

            import java.util.logging.Logger;

            import utils.Settings;


            public class ValidateEmergencyAddress {
              private static final Logger LOGGER = Logger.getLogger(ValidateEmergencyAddress.class.getName());

              public static void main(String[] args) {

                String projectId = Settings.getProjectId().orElse("MY_PROJECT_ID");
                String keyId = Settings.getKeyId().orElse("MY_KEY_ID");
                String keySecret = Settings.getKeySecret().orElse("MY_KEY_SECRET");

                String phoneNumber = Settings.getPhoneNumber().orElse("MY_SINCH_PHONE_NUMBER");

                Configuration configuration =
                    Configuration.builder()
                        .setProjectId(projectId)
                        .setKeyId(keyId)
                        .setKeySecret(keySecret)
                        .build();

                SinchClient client = new SinchClient(configuration);

                NumbersService numbersService = client.numbers().v1();

                LOGGER.info("Validate EmergencyAddress for: " + phoneNumber);

                EmergencyAddress emergencyAddress =
                    EmergencyAddress.builder()
                        .setStreetNumber("3500")
                        .setStreetInfo("Lenox Road NE")
                        .setCity("Atlanta")
                        .setState("GA")
                        .setPostalCode("30326")
                        .build();

                EmergencyAddressRequest request =
                    EmergencyAddressRequest.builder()
                        .setDisplayName("Emergency Address Display Name")
                        .setAddress(emergencyAddress)
                        .build();
                ValidateAddressResponse value = numbersService.validateEmergencyAddress(phoneNumber, request);

                LOGGER.info("Response: " + value);
              }
            }
components:
  parameters:
    projectId:
      name: projectId
      description: >-
        Found on your [Sinch Customer
        Dashboard](https://dashboard.sinch.com/settings/project-management).
        Settings > Projects.
      in: path
      required: true
      schema:
        type: string
        example: YOUR_projectId
    phoneNumber:
      name: phoneNumber
      description: >-
        Output only. The phone number in
        [E.164](https://community.sinch.com/t5/Glossary/E-164/ta-p/7537) format
        with leading `+`.
      in: path
      required: true
      schema:
        type: string
        example: '+12025550134'
        default: YOUR_selected_phoneNumber_from_search
    numberPattern.pattern:
      name: numberPattern.pattern
      description: >-
        Sequence of digits to search for. If you prefer or need certain digits
        in sequential order, you can enter the sequence of numbers here. For
        example, `2020`.
      in: query
      required: false
      schema:
        type: string
    numberPattern.searchPattern:
      name: numberPattern.searchPattern
      description: >-
        Search pattern to apply. The options are, `START`, `CONTAINS`, and
        `END`.
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/NumberPatternSearchPattern'
    regionCode:
      name: regionCode
      description: >-
        Region code to filter by. ISO 3166-1 alpha-2 country code of the phone
        number. Example: US, GB or SE.
      in: query
      required: true
      schema:
        type: string
        example: US
    type:
      name: type
      description: >-
        Number type to filter by. Options include, `MOBILE`, `LOCAL` or
        `TOLL_FREE`.
      in: query
      required: true
      schema:
        $ref: '#/components/schemas/NumberType'
    capabilities:
      name: capabilities
      description: Number capabilities to filter by SMS and/or VOICE.
      in: query
      required: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/NumberCapability'
    capability:
      name: capability
      description: Number capabilities to filter by SMS and/or VOICE.
      in: query
      required: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/NumberCapability'
    pageSize:
      name: pageSize
      description: The maximum number of items to return.
      in: query
      required: false
      schema:
        type: integer
        format: int32
    pageToken:
      name: pageToken
      description: The next page token value returned from a previous List request, if any.
      in: query
      required: false
      schema:
        type: string
    orderBy:
      name: orderBy
      description: Supported fields for ordering by `phoneNumber` or `displayName`.
      in: query
      required: false
      schema:
        type: string
        enum:
          - phoneNumber
          - displayName
        x-enumDescriptions:
          phoneNumber: Ordered by phone number
          displayName: Ordered by display name
        description: The ordering the request is supporting
  examples:
    SearchActivateSMSNumber:
      summary: >-
        Search and activate a number that matches criteria and sets the SMS
        configuration
      value:
        regionCode: US
        type: LOCAL
        capabilities:
          - SMS
        numberPattern:
          pattern: '+1208'
          searchPattern: START
        smsConfiguration:
          servicePlanId: YOUR_SMS_servicePlanId
          campaignId: YOUR_campaignId_from_TCR
        callbackUrl: https://www.your-callback-server.com/callback
    activateSMSNumberReq:
      summary: Activate number with SMS configuration
      value:
        smsConfiguration:
          servicePlanId: YOUR_SMS_servicePlanId
          campaignId: YOUR_campaignId_from_TCR
        callbackUrl: https://www.your-callback-server.com/callback
    activateSMSNumberRes:
      summary: Response for activing a number with SMS configuration
      value:
        phoneNumber: '+12025550134'
        projectId: 51bc3f40-f266-4ca8-8938-a1ed0ff32b9a
        displayName: MyPhoneNumber
        regionCode: US
        type: MOBILE
        capability:
          - SMS
        money:
          currencyCode: USD
          amount: '2.00'
        paymentIntervalMonths: 0
        nextChargeDate: '2024-08-24T14:15:22Z'
        expireAt: '2024-09-24T14:15:22Z'
        smsConfiguration:
          servicePlanId: YOUR_service_plan_id
          scheduledProvisioning:
            servicePlanId: YOUR_service_plan_id
            status: WAITING
            lastUpdatedTime: '2024-08-04T14:15:22Z'
            campaignId: YOUR_campaign_id
          campaignId: YOUR_campaign_id
    activateBothSMSandVoiceNumberReq:
      summary: Activate number with SMS and Voice configuration
      value:
        smsConfiguration:
          servicePlanId: YOUR_SMS_servicePlanId
        voiceConfiguration:
          type: RTC
          appId: YOUR_Voice_appId
        callbackUrl: https://www.your-callback-server.com/callback
    activateBothSMSandVoiceNumberRes:
      summary: Response for activing a number with both SMS and Voice configuration
      value:
        phoneNumber: '+12025550134'
        projectId: 51bc3f40-f266-4ca8-8938-a1ed0ff32b9a
        displayName: MyPhoneNumber
        regionCode: US
        type: MOBILE
        capability:
          - SMS
          - VOICE
        money:
          currencyCode: USD
          amount: '2.00'
        paymentIntervalMonths: 0
        nextChargeDate: '2024-08-24T14:15:22Z'
        expireAt: '2024-09-24T14:15:22Z'
        smsConfiguration:
          servicePlanId: YOUR_service_plan_id
          scheduledProvisioning:
            servicePlanId: ''
            status: WAITING
            lastUpdatedTime: '2024-08-04T14:15:22Z'
            campaignId: YOUR_campaign_id
          campaignId: YOUR_campaign_id
        voiceConfiguration:
          type: RTC
          lastUpdatedTime: '2024-09-24T14:15:22Z'
          scheduledVoiceProvisioning:
            type: RTC
            lastUpdatedTime: '2024-09-24T14:15:22Z'
            status: WAITING
            appId: YOUR_app_id
          appId: YOUR_app_id
    activateVoiceNumberReq:
      summary: Activate number with Voice configuration
      value:
        voiceConfiguration:
          type: RTC
          appId: YOUR_app_id
        callbackUrl: https://www.your-callback-server.com/callback
    activateVoiceNumberRes:
      summary: Response for activing a number with Voice configuration
      value:
        phoneNumber: '+12025550134'
        projectId: 51bc3f40-f266-4ca8-8938-a1ed0ff32b9a
        displayName: MyPhoneNumber
        regionCode: US
        type: MOBILE
        capability:
          - VOICE
        money:
          currencyCode: USD
          amount: '2.00'
        paymentIntervalMonths: 0
        nextChargeDate: '2024-08-24T14:15:22Z'
        expireAt: '2024-09-24T14:15:22Z'
        voiceConfiguration:
          type: RTC
          lastUpdatedTime: '2024-09-24T14:15:22Z'
          scheduledVoiceProvisioning:
            type: RTC
            lastUpdatedTime: '2024-09-24T14:15:22Z'
            status: WAITING
            appId: YOUR_app_id
          appId: YOUR_app_id
    activateESTNumberReq:
      summary: Activate number with Elastic SIP Trunking configuration
      value:
        voiceConfiguration:
          type: EST
          trunkId: YOUR_trunk_id
        callbackUrl: https://www.your-callback-server.com/callback
    activateESTNumberRes:
      summary: Response for activing a number with Elastic SIP Trunking configuration
      value:
        phoneNumber: '+12025550134'
        projectId: 51bc3f40-f266-4ca8-8938-a1ed0ff32b9a
        displayName: MyPhoneNumber
        regionCode: US
        type: LOCAL
        capability:
          - VOICE
        money:
          currencyCode: USD
          amount: '2.00'
        paymentIntervalMonths: 0
        nextChargeDate: '2024-08-24T14:15:22Z'
        expireAt: '2024-09-24T14:15:22Z'
        voiceConfiguration:
          type: EST
          lastUpdatedTime: '2024-09-24T14:15:22Z'
          scheduledVoiceProvisioning:
            type: EST
            lastUpdatedTime: '2024-09-24T14:15:22Z'
            status: WAITING
            trunkId: YOUR_trunk_id
          trunkId: YOUR_trunk_id
    activateFaxNumberReq:
      summary: Activate number with Fax configuration
      value:
        voiceConfiguration:
          type: FAX
          serviceId: YOUR_service_id
        callbackUrl: https://www.your-callback-server.com/callback
    activateFaxNumberRes:
      summary: Response for activing a number with Fax configuration
      value:
        phoneNumber: '+12025550134'
        projectId: 51bc3f40-f266-4ca8-8938-a1ed0ff32b9a
        displayName: MyPhoneNumber
        regionCode: US
        type: LOCAL
        capability:
          - VOICE
        money:
          currencyCode: USD
          amount: '2.00'
        paymentIntervalMonths: 0
        nextChargeDate: '2024-08-24T14:15:22Z'
        expireAt: '2024-09-24T14:15:22Z'
        voiceConfiguration:
          type: FAX
          lastUpdatedTime: '2024-09-24T14:15:22Z'
          scheduledVoiceProvisioning:
            type: FAX
            lastUpdatedTime: '2024-09-24T14:15:22Z'
            status: WAITING
            serviceId: YOUR_service_id
          serviceId: YOUR_service_id
    updateSMSandVoiceNumber:
      summary: Update number with SMS and Voice configuration
      value:
        displayName: MyPhoneNumber
        smsConfiguration:
          servicePlanId: string
          campaignId: YOUR_campaignId_from_TCR
        voiceConfiguration:
          type: RTC
          appId: YOUR_Voice_appId
        callbackUrl: https://www.your-callback-server.com/callback
    updateSMSNumber:
      summary: Update number with SMS configuration
      value:
        displayName: MyPhoneNumber
        smsConfiguration:
          servicePlanId: YOUR_servicePlanId
          campaignId: YOUR_campaignId_from_TCR
        callbackUrl: https://www.your-callback-server.com/callback
    updateVoiceNumber:
      summary: Update number with Voice configuration
      value:
        displayName: MyPhoneNumber
        voiceConfiguration:
          type: RTC
          appId: YOUR_Voice_appId
        callbackUrl: https://www.your-callback-server.com/callback
    perfectMatch:
      summary: Address validation is a perfect match
      value:
        phoneNumber: '+12025550134'
        displayName: User Name
        validatedAddress:
          streetNumber: '12345'
          streetInfo: Main St
          location: Apt 5
          city: Springfield
          state: IL
          postalCode: '62701'
          postalCodePlusFour: '1234'
        validationResult: EXACT_MATCH
        validationMessage: Address is a perfect match
        correctedAddress: {}
        candidateAddresses: []
    nearMatch:
      summary: Address validation is a near match to another known address
      value:
        phoneNumber: '+12025550134'
        displayName: User Name
        validatedAddress:
          streetNumber: '12345'
          streetInfo: Main Street
          location: Apt 5
          city: Springfield
          state: IL
          postalCode: '62701'
          postalCodePlusFour: '1234'
        validationResult: NEAR_MATCH
        validationMessage: Address is a near match
        correctedAddress:
          streetNumber: '12345'
          streetInfo: Main St
          location: Apt 5
          city: Springfield
          state: IL
          postalCode: '62701'
          postalCodePlusFour: '1234'
        candidateAddresses: []
    noMatch:
      summary: Address validation doesn't match any known address
      value:
        phoneNumber: '+12025550134'
        displayName: User Name
        validatedAddress:
          streetNumber: '12345'
          streetInfo: Main St
          location: Apt 5
          city: Springfield
          state: IL
          postalCode: '62701'
          postalCodePlusFour: '1234'
        validationResult: NO_MATCH
        validationMessage: Address doesn't match any known address
        correctedAddress: {}
        candidateAddresses:
          - streetNumber: '67890'
            streetInfo: Elm St
            location: Apt 10
            city: Springfield
            state: IL
            postalCode: '62702'
            postalCodePlusFour: '5678'
          - streetNumber: '54321'
            streetInfo: Oak St
            location: Apt 20
            city: Springfield
            state: IL
            postalCode: '62703'
            postalCodePlusFour: '9876'
  requestBodies:
    ActiveNumberRequest:
      description: The number body to be updated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ActiveNumberRequest'
          examples:
            updateSMSandVoiceNumber:
              $ref: '#/components/examples/updateSMSandVoiceNumber'
            updateSMSNumber:
              $ref: '#/components/examples/updateSMSNumber'
            updateVoiceNumber:
              $ref: '#/components/examples/updateVoiceNumber'
    RentNumberRequest:
      description: The request to rent a number.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RentNumberRequest'
          examples:
            activateBothSMSandVoiceNumber:
              $ref: '#/components/examples/activateBothSMSandVoiceNumberReq'
            activateSMSNumber:
              $ref: '#/components/examples/activateSMSNumberReq'
            activateVoiceNumber:
              $ref: '#/components/examples/activateVoiceNumberReq'
            activateESTNumber:
              $ref: '#/components/examples/activateESTNumberReq'
            activateFaxNumber:
              $ref: '#/components/examples/activateFaxNumberReq'
    ProvisionEmergencyAddressRequest:
      description: Request to provision an emergency address for a number.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EmergencyAddressRequest'
          example:
            displayName: New Emergency Address
            address:
              streetNumber: '12345'
              streetInfo: Main St
              city: Springfield
              state: IL
              postalCode: '62701'
    ValidateEmergencyAddressRequest:
      description: Request to validate an emergency address for a number.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EmergencyAddressRequest'
          example:
            displayName: New Emergency Address
            address:
              streetNumber: '12345'
              streetInfo: Main St
              city: Springfield
              state: IL
              postalCode: '62701'
  responses:
    ActiveNumberResponse:
      description: >-
        A successful response, or an
        [Error](/docs/numbers/api-reference/error-codes/status-codes/).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ActiveNumberResponse'
          examples:
            activateBothSMSandVoiceNumber:
              $ref: '#/components/examples/activateBothSMSandVoiceNumberRes'
            activateSMSNumber:
              $ref: '#/components/examples/activateSMSNumberRes'
            activateVoiceNumber:
              $ref: '#/components/examples/activateVoiceNumberRes'
            activateESTNumber:
              $ref: '#/components/examples/activateESTNumberRes'
            activateFaxNumber:
              $ref: '#/components/examples/activateFaxNumberRes'
    AvailableNumberResponse:
      description: A successful response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AvailableNumber'
    ListActiveNumbersResponse:
      description: >-
        A successful response, or an
        [Error](/docs/numbers/api-reference/error-codes/status-codes/).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ListActiveNumbersResponse'
    ListAvailableNumbersResponse:
      description: >-
        A successful response, or an
        [Error](/docs/numbers/api-reference/error-codes/status-codes/).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ListAvailableNumbersResponse'
    ListAvailableRegionsResponse:
      description: >-
        A successful response, or an
        [Error](/docs/numbers/api-reference/error-codes/status-codes/).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ListAvailableRegionsResponse'
    EmergencyAddressResponse:
      description: >-
        A successful response, or an
        [error](/docs/numbers/api-reference/error-codes/status-codes/)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EmergencyAddress'
    PermissionDenied:
      description: >-
        PERMISSION_DENIED: improper credentials. Be sure your projectId,
        username and password are correct.
      content:
        application/json:
          schema: {}
          example:
            error:
              code: 403
              message: ''
              status: PERMISSION_DENIED
              details: []
  schemas:
    RentAnyNumberRequest:
      title: RentAnyNumberRequest
      required:
        - regionCode
        - type
      type: object
      properties:
        numberPattern:
          $ref: '#/components/schemas/NumberPattern'
        regionCode:
          type: string
          description: >-
            Region code to filter by. ISO 3166-1 alpha-2 country code of the
            phone number. Example: `US`, `GB` or `SE`.
        type:
          $ref: '#/components/schemas/NumberType'
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/NumberCapability'
          description: Number capabilities to filter by, `SMS` and/or `VOICE`.
        smsConfiguration:
          $ref: '#/components/schemas/smsConfiguration'
        voiceConfiguration:
          $ref: '#/components/schemas/VoiceConfiguration'
        callbackUrl:
          type: string
          description: >-
            The callback URL to be called for a rented number's provisioning /
            deprovisioning operations.
          example: https://www.your-callback-server.com/callback
      description: >-
        Request message for searching and renting in one go any number that
        matches the search criteria.
    NumberPatternSearchPattern:
      type: string
      enum:
        - START
        - CONTAINS
        - END
      x-enumDescriptions:
        START: Numbers that start with the provided sequence of digits.
        CONTAINS: Numbers that contain the sequence of digits entered.
        END: Numbers that end with the sequence of digits entered.
      description: The pattern to apply to searches.
      title: Search Pattern
    money:
      type: object
      description: An object giving details on currency code and the amount charged.
      properties:
        currencyCode:
          type: string
          example: USD
          description: >-
            The 3-letter currency code defined in [ISO
            4217](https://www.iso.org/iso-4217-currency-codes.html).
        amount:
          type: string
          example: '2.00'
          description: >-
            The amount in decimal form.

            For example `2.00`.

            There are no guarantees on the precision unless documented by the
            message origin. The amount cannot be updated and is read-only.
      title: Money
    ActiveNumberRequest:
      type: object
      properties:
        displayName:
          type: string
          description: User supplied name for the phone number.
        smsConfiguration:
          $ref: '#/components/schemas/smsConfiguration'
        voiceConfiguration:
          $ref: '#/components/schemas/VoiceConfiguration'
        callbackUrl:
          type: string
          description: >-
            The callback URL to be called for a rented number's provisioning /
            deprovisioning operations.
      description: >-
        The phone number that has been rented by a customer and assigned to a
        project.
      title: Active Number Request
    ActiveNumberResponse:
      type: object
      properties:
        phoneNumber:
          type: string
          example: '+12025550134'
          description: >-
            The phone number in
            [E.164](https://community.sinch.com/t5/Glossary/E-164/ta-p/7537)
            format with leading `+`. Example: `+12025550134`.
        projectId:
          type: string
          example: 51bc3f40-f266-4ca8-8938-a1ed0ff32b9a
          description: >-
            Project ID. Your project ID can be found on your [Sinch Customer
            Dashboard](https://dashboard.sinch.com/settings/project-management).
        displayName:
          type: string
          description: User supplied name for the phone number.
        regionCode:
          type: string
          example: US
          description: >-
            ISO 3166-1 alpha-2 country code of the phone number. Example US, UK
            or SE.
          readOnly: true
        type:
          $ref: '#/components/schemas/NumberType'
        capability:
          description: The capability of the number.
          type: array
          example:
            - SMS
          items:
            $ref: '#/components/schemas/NumberCapability'
        money:
          $ref: '#/components/schemas/money'
        paymentIntervalMonths:
          type: integer
          format: int32
          description: How often the recurring price is charged in months.
          readOnly: true
        nextChargeDate:
          type: string
          format: date-time
          description: The date of the next charge.
          readOnly: true
        expireAt:
          type: string
          format: date-time
          description: >-
            The timestamp when the subscription will expire if an expiration
            date has been set.
          readOnly: true
        smsConfiguration:
          $ref: '#/components/schemas/smsConfiguration'
        voiceConfiguration:
          $ref: '#/components/schemas/VoiceConfiguration'
        callbackUrl:
          type: string
          description: >-
            The callback URL to be called for a rented number's provisioning /
            deprovisioning operations.
          example: https://www.your-callback-server.com/callback
      description: >-
        The phone number that has been bought by a customer and assigned to a
        project.
      title: Active Number Response
    AvailableNumber:
      type: object
      properties:
        phoneNumber:
          type: string
          example: '+12025550134'
          description: >-
            The phone number in
            [E.164](https://community.sinch.com/t5/Glossary/E-164/ta-p/7537)
            format with leading `+`. Example `+12025550134`.
          readOnly: true
        regionCode:
          type: string
          example: US
          description: >-
            ISO 3166-1 alpha-2 country code of the phone number. Example: US, UK
            or SE.
          readOnly: true
        type:
          $ref: '#/components/schemas/NumberType'
        capability:
          type: array
          description: The capability of the number.
          example:
            - SMS
            - VOICE
          items:
            $ref: '#/components/schemas/NumberCapability'
        setupPrice:
          $ref: '#/components/schemas/money'
        monthlyPrice:
          $ref: '#/components/schemas/money'
        paymentIntervalMonths:
          type: integer
          format: int32
          description: How often the recurring price is charged in months.
          readOnly: true
        supportingDocumentationRequired:
          type: boolean
          description: >-
            Whether or not supplementary documentation will be required to
            complete the number rental.
          readOnly: true
      description: >-
        The phone numbers that are available to be rented in
        [dashboard.sinch.com](https://dashboard.sinch.com/numbers/buy-numbers)
        or via the public numbers API.
      title: Available Number
    AvailableRegion:
      type: object
      properties:
        regionCode:
          type: string
          example: US
          description: 'ISO 3166-1 alpha-2 region code. Examples: US, UK or SE.'
          readOnly: true
        regionName:
          type: string
          example: United States
          description: >-
            Display name of the region. Examples: United States, United Kingdom
            or Sweden.
          readOnly: true
        types:
          type: array
          example:
            - MOBILE
          items:
            $ref: '#/components/schemas/NumberType'
          description: >-
            A list of the different number types available. Examples: `MOBILE`
            or `LOCAL`.
          readOnly: true
      description: A region for which numbers are provided.
      title: Available Region
    ListActiveNumbersResponse:
      type: object
      properties:
        activeNumbers:
          type: array
          items:
            $ref: '#/components/schemas/ActiveNumberResponse'
          description: >-
            List of numbers associated to the client project specified in
            `ListActiveNumbers`.
        nextPageToken:
          type: string
          title: The token to be used for listing the next page.
        totalSize:
          type: integer
          format: int32
          title: The maximum number of results returned.
      description: Response message to list your active phone numbers.
      title: Active Numbers Response
    ListAvailableNumbersResponse:
      type: object
      properties:
        availableNumbers:
          type: array
          items:
            $ref: '#/components/schemas/AvailableNumber'
          description: List of available phone numbers.
      description: Response message to list available phone numbers.
      title: Available Numbers Response
    ListAvailableRegionsResponse:
      type: object
      properties:
        availableRegions:
          type: array
          items:
            $ref: '#/components/schemas/AvailableRegion'
          title: List of regions for which numbers are provided.
      description: Response message to list regions for which numbers are provided.
      title: List Available Regions Response
    NumberCapability:
      type: string
      enum:
        - SMS
        - VOICE
      x-enumDescriptions:
        SMS: The SMS product can use the number.
        VOICE: The Voice product can use the number.
      default: SMS
      description: 'The capabilities the phone number supports: SMS, Voice, or both'
      title: Capability
    NumberPattern:
      type: object
      properties:
        pattern:
          type: string
          description: Sequence of digits to search for.
        searchPattern:
          $ref: '#/components/schemas/NumberPatternSearchPattern'
      title: Search Pattern
    NumberType:
      type: string
      enum:
        - MOBILE
        - LOCAL
        - TOLL_FREE
      x-enumDescriptions:
        MOBILE: Numbers that belong to a specific range.
        LOCAL: Numbers that are assigned to a specific geographic region.
        TOLL_FREE: >-
          Numbers that are free of charge for the calling party but billed for
          all arriving calls.
      default: MOBILE
      description: The number type.
      title: Type
    ProvisioningStatus:
      default: WAITING
      description: >-
        The provisioning status. It will be either `WAITING`, `IN_PROGRESS` or
        `FAILED`. If the provisioning fails, a reason for the failure will be
        provided. [See a full list of provisioning error
        descriptions]<(https://developers.sinch.com/docs/numbers/api-reference/error-codes/provisioning-errors)
        and troubleshooting recommendations.
      enum:
        - PROVISIONING_STATUS_UNSPECIFIED
        - WAITING
        - IN_PROGRESS
        - FAILED
      x-enumDescriptions:
        PROVISIONING_STATUS_UNSPECIFIED: The status is currently unknown.
        WAITING: Waiting for provisioning
        IN_PROGRESS: Provisioning in progress
        FAILED: >-
          Provisioning failed. See [provisioning error
          descriptions](https://developers.sinch.com/docs/numbers/api-reference/error-codes/provisioning-errors)
      title: Provisioning Status
    RentNumberRequest:
      type: object
      properties:
        smsConfiguration:
          $ref: '#/components/schemas/smsConfiguration'
        voiceConfiguration:
          $ref: '#/components/schemas/VoiceConfiguration'
        callbackUrl:
          type: string
          description: >-
            The callback URL to be called for a rented number's provisioning /
            deprovisioning operations.
      description: Request message for renting a phone number.
      title: Rent Number Request
    scheduledProvisioning:
      type: object
      description: >-
        Represents the ongoing or failed scheduled provisioning job. This field
        will be empty if the number was both successfully provisioned to the SMS
        platform and linked to the 10DLC campaign.
      properties:
        servicePlanId:
          type: string
          description: >-
            The SMS service plan that the scheduled provisioning job will
            configure with the number.
          readOnly: true
        campaignId:
          type: string
          description: >-
            TCR campaign ID that the scheduled provisioning job will configure
            with the number.
          readOnly: true
        status:
          $ref: '#/components/schemas/ProvisioningStatus'
        lastUpdatedTime:
          type: string
          format: date-time
          description: Timestamp when the status was last updated.
          readOnly: true
        errorCodes:
          type: array
          items:
            $ref: '#/components/schemas/SmsErrorCode'
          readOnly: true
      title: Scheduled Provisioning
    smsConfiguration:
      type: object
      required:
        - servicePlanId
      properties:
        servicePlanId:
          type: string
          description: >-
            The `servicePlanId` can be found in the [Sinch Customer
            Dashboard](https://dashboard.sinch.com/sms/api/rest). The service
            plan ID is what ties this number to the configured SMS service.
        campaignId:
          type: string
          description: >-
            Only for US phone numbers. This `campaignId` is required to send SMS
            traffic to US; click
            [here](https://community.sinch.com/t5/10DLC/What-is-10DLC/ta-p/7845)
            to read more about 10DLC A2P messaging. So, it is the current
            campaign ID for this number. The `campaignId` is found on your TCR
            platform.
        scheduledProvisioning:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/scheduledProvisioning'
      description: >-
        The current SMS configuration for this number.


        Once the `servicePlanId` is sent, it enters scheduled provisioning.


        The status of scheduled provisioning will show under a
        `scheduledProvisioning` object if it's still running. Once processed
        successfully, the `servicePlanId` sent will appear directly under the
        `smsConfiguration` object.
      title: SMS Configuration
    SmsErrorCode:
      type: string
      x-enumDescriptions:
        ERROR_CODE_UNSPECIFIED: Code not specified.
        INTERNAL_ERROR: Internal server error.
        SMS_PROVISIONING_FAILED: Provisioning for SMS failed.
        CAMPAIGN_PROVISIONING_FAILED: Provisioning for campaign failed.
        CAMPAIGN_NOT_AVAILABLE: The specified campaign is not available.
        EXCEEDED_10DLC_LIMIT: Exceeded the 10DLC limit.
        NUMBER_PROVISIONING_FAILED: Failed to provision the number.
        PARTNER_SERVICE_UNAVAILABLE: The third party service is unavailable.
        CAMPAIGN_PENDING_ACCEPTANCE: The campaign is awaiting acceptance.
        MNO_SHARING_ERROR: Sharing error.
        CAMPAIGN_EXPIRED: The specific campaign has expired.
        CAMPAIGN_MNO_REJECTED: The MNO for the campaign was rejected.
        CAMPAIGN_MNO_SUSPENDED: The MNO for the campaign was suspended.
        CAMPAIGN_MNO_REVIEW: The MNO for the campaign is under review.
        INSUFFICIENT_BALANCE: The credit balance for the account is insufficient to cover the fees.
        MOCK_CAMPAIGN_NOT_ALLOWED: Mock campaign is not permitted.
        TFN_NOT_ALLOWED: The Toll-Free number is not allowed.
        INVALID_NNID: The specified NNID is invalid.
      enum:
        - ERROR_CODE_UNSPECIFIED
        - INTERNAL_ERROR
        - SMS_PROVISIONING_FAILED
        - CAMPAIGN_PROVISIONING_FAILED
        - CAMPAIGN_NOT_AVAILABLE
        - EXCEEDED_10DLC_LIMIT
        - NUMBER_PROVISIONING_FAILED
        - PARTNER_SERVICE_UNAVAILABLE
        - CAMPAIGN_PENDING_ACCEPTANCE
        - MNO_SHARING_ERROR
        - CAMPAIGN_EXPIRED
        - CAMPAIGN_MNO_REJECTED
        - CAMPAIGN_MNO_SUSPENDED
        - CAMPAIGN_MNO_REVIEW
        - INSUFFICIENT_BALANCE
        - MOCK_CAMPAIGN_NOT_ALLOWED
        - TFN_NOT_ALLOWED
        - INVALID_NNID
      description: >-
        The error codes that show the reason of failure of a scheduled
        provisioning
      title: SMS Error Code
    VoiceApplicationType:
      type: string
      description: The voice application type. Examples are RTC, EST, FAX
      x-enumDescriptions:
        RTC: Voice [see documentation](https://developers.sinch.com/docs/voice)
        EST: >-
          Elastic SIP Trunking [see
          documentation](https://developers.sinch.com/docs/est)
        FAX: >-
          FAX application [see
          documentation](https://developers.sinch.com/docs/fax/overview)
      enum:
        - RTC
        - EST
        - FAX
      default: RTC
    VoiceConfigurationCommon:
      title: Common VoiceConfiguration fields
      type: object
      properties:
        type:
          $ref: '#/components/schemas/VoiceApplicationType'
        lastUpdatedTime:
          type: string
          description: Timestamp when the status was last updated.
          format: date-time
          readOnly: true
        scheduledVoiceProvisioning:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/ScheduledVoiceProvisioning'
    VoiceTrunkId:
      type: object
      properties:
        trunkId:
          type: string
          description: >-
            The trunk ID if the type is EST. The `trunkId` can be found in your
            [Sinch Customer
            Dashboard](https://dashboard.sinch.com/trunks/your-trunks).
    VoiceServiceId:
      type: object
      properties:
        serviceId:
          type: string
          description: >-
            The service ID if the type is FAX. The `serviceId` can be found in
            your [Sinch Customer
            Dashboard](https://dashboard.sinch.com/fax/services).
    VoiceAppId:
      type: object
      properties:
        appId:
          type: string
          description: >-
            Your app ID for the Voice API. The `appId` can be found in your
            [Sinch Customer Dashboard](https://dashboard.sinch.com/voice/apps).
    VoiceConfigurationRTC:
      title: RTC VoiceConfiguration
      type: object
      allOf:
        - $ref: '#/components/schemas/VoiceConfigurationCommon'
        - $ref: '#/components/schemas/VoiceAppId'
    VoiceConfigurationEST:
      title: EST VoiceConfiguration
      type: object
      required:
        - type
      allOf:
        - $ref: '#/components/schemas/VoiceConfigurationCommon'
        - $ref: '#/components/schemas/VoiceTrunkId'
    VoiceConfigurationFAX:
      title: FAX VoiceConfiguration
      type: object
      required:
        - type
      allOf:
        - $ref: '#/components/schemas/VoiceConfigurationCommon'
        - $ref: '#/components/schemas/VoiceServiceId'
    VoiceConfiguration:
      title: VoiceConfiguration
      type: object
      oneOf:
        - $ref: '#/components/schemas/VoiceConfigurationRTC'
        - $ref: '#/components/schemas/VoiceConfigurationEST'
        - $ref: '#/components/schemas/VoiceConfigurationFAX'
      discriminator:
        propertyName: type
        mapping:
          RTC: '#/components/schemas/VoiceConfigurationRTC'
          EST: '#/components/schemas/VoiceConfigurationEST'
          FAX: '#/components/schemas/VoiceConfigurationFAX'
      description: >-
        The current voice configuration for this number. During scheduled
        provisioning, the app ID, service ID, or trunk ID value may be empty in
        a response if it is still processing or if it has failed. The status of
        scheduled provisioning will show under a `scheduledVoiceProvisioning`
        object if it's still running. Once processed successfully, the
        `appId`/`serviceId`/`trunkId` sent will appear directly under the
        `voiceConfiguration` object.
    ScheduledVoiceProvisioningCommon:
      type: object
      required:
        - type
      allOf:
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/VoiceApplicationType'
            lastUpdatedTime:
              type: string
              description: Timestamp when the status was last updated.
              format: date-time
              readOnly: true
            status:
              $ref: '#/components/schemas/ProvisioningStatus'
    ScheduledVoiceProvisioningEST:
      type: object
      allOf:
        - $ref: '#/components/schemas/ScheduledVoiceProvisioningCommon'
        - $ref: '#/components/schemas/VoiceTrunkId'
    ScheduledVoiceProvisioningFAX:
      type: object
      allOf:
        - $ref: '#/components/schemas/ScheduledVoiceProvisioningCommon'
        - $ref: '#/components/schemas/VoiceServiceId'
    ScheduledVoiceProvisioningRTC:
      type: object
      allOf:
        - $ref: '#/components/schemas/ScheduledVoiceProvisioningCommon'
        - $ref: '#/components/schemas/VoiceAppId'
    ScheduledVoiceProvisioning:
      type: object
      readOnly: true
      description: >-
        Represents the ongoing or failed scheduled voice provisioning job. This
        field will be empty if the number was successfully provisioned
        provisioned for voice.
      required:
        - type
      oneOf:
        - $ref: '#/components/schemas/ScheduledVoiceProvisioningEST'
        - $ref: '#/components/schemas/ScheduledVoiceProvisioningFAX'
        - $ref: '#/components/schemas/ScheduledVoiceProvisioningRTC'
      discriminator:
        propertyName: type
        mapping:
          EST: '#/components/schemas/ScheduledVoiceProvisioningEST'
          FAX: '#/components/schemas/ScheduledVoiceProvisioningFAX'
          RTC: '#/components/schemas/ScheduledVoiceProvisioningRTC'
      title: Scheduled Voice Provisioning
    CallbackConfiguration:
      description: >-
        Response message containing the callbacks configuration for a specific
        project.
      type: object
      properties:
        projectId:
          type: string
          description: ID of the project the configuration belongs to.
          example: a99aa9aa-b888-777c-dd6d-ee55e5555555
        hmacSecret:
          type: string
          description: >-
            The HMAC secret used for hashing the callback body using the
            HMAC-SHA1 algorithm - and for creating the `X-Sinch-Signature`
            header.
          example: YOUR_hmac_secret
    CallbackConfigurationUpdate:
      title: CallbackConfigurationUpdate
      type: object
      properties:
        hmacSecret:
          type: string
          description: The HMAC secret to be updated for the specified project
      description: >-
        The request to update the callbacks configuration for the current
        project.
    CallbackPayload:
      type: object
      properties:
        eventId:
          type: string
          description: The ID of the event.
          example: abcd1234efghijklmnop567890
        timestamp:
          type: string
          description: >-
            The date and time when the callback was created and added to the
            callbacks queue.
          example: '2023-06-06T07:45:27.785357'
        projectId:
          type: string
          description: The ID of the project to which the event belongs.
          example: abcd12ef-ab12-ab12-bc34-abcdef123456
        resourceId:
          type: string
          description: >-
            The unique identifier of the resource, depending on the resource
            type. For example, a phone number, a hosting order ID, or a brand
            ID.
          example: '+12345612345'
        resourceType:
          $ref: '#/components/schemas/ResourceType'
        eventType:
          type: string
          description: The type of the event.
          enum:
            - PROVISIONING_TO_SMS_PLATFORM
            - DEPROVISIONING_FROM_SMS_PLATFORM
            - PROVISIONING_TO_CAMPAIGN
            - DEPROVISIONING_FROM_CAMPAIGN
            - PROVISIONING_TO_VOICE_PLATFORM
            - DEPROVISIONING_TO_VOICE_PLATFORM
          x-enumDescriptions:
            PROVISIONING_TO_SMS_PLATFORM: An event that occurs when a number is linked to a Service Plan ID.
            DEPROVISIONING_FROM_SMS_PLATFORM: >-
              An event that occurs when a number is unlinked from a Service Plan
              ID.
            PROVISIONING_TO_CAMPAIGN: An event that occurs when a number is linked to a Campaign.
            DEPROVISIONING_FROM_CAMPAIGN: An event that occurs when a number is unlinked from a Campaign.
            PROVISIONING_TO_VOICE_PLATFORM: >-
              An event that occurs when a number is enabled for Voice
              operations.
            DEPROVISIONING_TO_VOICE_PLATFORM: >-
              An event that occurs when a number is disabled for Voice
              operations.
          example: PROVISIONING_TO_CAMPAIGN
        status:
          type: string
          description: The status of the event. For example, `SUCCEEDED` or `FAILED`.
          x-enumDescriptions:
            SUCCEEDED: The event has succeeded.
            FAILED: The event has failed.
          enum:
            - SUCCEEDED
            - FAILED
          example: FAILED
        failureCode:
          type: string
          description: >-
            If the status is FAILED, a failure code will be provided. For
            numbers provisioning to SMS platform, there won't be any extra
            `failureCode`, as the result is binary. For campaign
            provisioning-related failures, refer to the list for the possible
            values.
          example: CAMPAIGN_NOT_AVAILABLE
          enum:
            - CAMPAIGN_NOT_AVAILABLE
            - EXCEEDED_10DLC_LIMIT
            - NUMBER_PROVISIONING_FAILED
            - PARTNER_SERVICE_UNAVAILABLE
            - CAMPAIGN_PENDING_ACCEPTANCE
            - MNO_SHARING_ERROR
            - CAMPAIGN_PROVISIONING_FAILED
            - CAMPAIGN_EXPIRED
            - CAMPAIGN_MNO_REJECTED
            - CAMPAIGN_MNO_SUSPENDED
            - CAMPAIGN_MNO_REVIEW
            - INSUFFICIENT_BALANCE
            - MOCK_CAMPAIGN_NOT_ALLOWED
            - TFN_NOT_ALLOWED
            - INVALID_NNID
          x-enumDescriptions:
            CAMPAIGN_NOT_AVAILABLE: The specified campaign is not available.
            EXCEEDED_10DLC_LIMIT: Exceeded the limit for 10DLC.
            NUMBER_PROVISIONING_FAILED: Provisioning the number failed.
            PARTNER_SERVICE_UNAVAILABLE: The third party service is unavailable.
            CAMPAIGN_PENDING_ACCEPTANCE: The campaign is not yet accepted.
            MNO_SHARING_ERROR: Error with MNO.
            CAMPAIGN_PROVISIONING_FAILED: The campaign failed to provision.
            CAMPAIGN_EXPIRED: The campaign expired.
            CAMPAIGN_MNO_REJECTED: The campaign MNO was rejected.
            CAMPAIGN_MNO_SUSPENDED: The campaign MNO was suspended.
            CAMPAIGN_MNO_REVIEW: The campaign MNO is under review.
            INSUFFICIENT_BALANCE: Not enough credit in the account.
            MOCK_CAMPAIGN_NOT_ALLOWED: Provisioning not allowed for mock campaigns.
            TFN_NOT_ALLOWED: Toll free numbers not allowed.
            INVALID_NNID: Invalid NNID.
    InvalidArgument:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              enum:
                - 400
              x-enumDescriptions:
                '400': The HTTP status code for invalid arguments.
            message:
              type: string
            status:
              type: string
              enum:
                - INVALID_ARGUMENT
              x-enumDescriptions:
                INVALID_ARGUMENT: The request contained invalid arguments.
            details:
              type: array
              items:
                $ref: '#/components/schemas/BadRequest'
    BadRequest:
      type: object
      properties:
        type:
          type: string
          enum:
            - BadRequest
          x-enumDescriptions:
            BadRequest: The request was malformed in some way.
        fieldViolations:
          type: array
          items:
            $ref: '#/components/schemas/FieldViolation'
    FieldViolation:
      type: object
      properties:
        field:
          type: string
        description:
          type: string
    NotFoundErrorDetails:
      type: object
      properties:
        type:
          type: string
        resourceType:
          type: string
          description: The type of the resource that was not found.
        resourceName:
          type: string
          description: The name of the resource that was not found.
        owner:
          type: string
          description: The owner of the resource that was not found.
        description:
          type: string
          description: A description of the error.
    NotFound:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              enum:
                - 404
              x-enumDescriptions:
                '404': The HTTP status code for a resource not found.
            message:
              type: string
            status:
              type: string
              enum:
                - NOT_FOUND
              x-enumDescriptions:
                NOT_FOUND: The request resource could not be found.
            details:
              type: array
              items:
                $ref: '#/components/schemas/NotFoundErrorDetails'
    InternalError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              enum:
                - 500
              x-enumDescriptions:
                '500': The HTTP status code for an internal server error.
            message:
              type: string
            status:
              type: string
              enum:
                - INTERNAL
                - UNKNOWN
              x-enumDescriptions:
                INTERNAL: An internal server error.
                UNKNOWN: Some unknown error.
            details:
              type: array
              items:
                type: object
    EmergencyAddress:
      type: object
      description: Details of the emergency address.
      title: Emergency Address
      properties:
        streetNumber:
          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'
    ValidateAddressResponse:
      type: object
      description: Response object containing details of the emergency address.
      title: Validate Emergency Address Response
      properties:
        phoneNumber:
          type: string
          description: The phone number in E.164 format with leading `+`.
          example: '+12025550134'
        displayName:
          type: string
          description: User supplied name for the phone number.
          example: User Name
        validatedAddress:
          $ref: '#/components/schemas/EmergencyAddress'
        validationResult:
          $ref: '#/components/schemas/AddressValidationResultCode'
        validationMessage:
          type: string
          description: Validation result message
          example: Corrected to valid address
        correctedAddress:
          $ref: '#/components/schemas/EmergencyAddress'
        candidateAddresses:
          type: array
          items:
            $ref: '#/components/schemas/EmergencyAddress'
          description: >-
            List of candidate addresses (only available if validationResult ==
            NO_MATCH)
    EmergencyAddressRequest:
      type: object
      description: Request for emergency address.
      title: Emergency Address Request
      required:
        - displayName
        - address
      properties:
        displayName:
          type: string
          description: Name for emergency address.
          example: New emergency address
        address:
          required:
            - streetNumber
            - streetInfo
            - city
            - state
            - postalCode
          allOf:
            - $ref: '#/components/schemas/EmergencyAddress'
    AddressValidationResultCode:
      type: string
      enum:
        - ADDRESS_VALIDATION_RESULT_CODE_UNSPECIFIED
        - EXACT_MATCH
        - NEAR_MATCH
        - NO_MATCH
      description: Enum representing the result of address validation.
      x-enumDescriptions:
        ADDRESS_VALIDATION_RESULT_CODE_UNSPECIFIED: Undetermined Result
        EXACT_MATCH: The address is perfect as sent
        NEAR_MATCH: The result was a close enough match and has been corrected
        NO_MATCH: The result is not close enough
    ResourceType:
      type: string
      description: The type of the resource.
      x-enumDescriptions:
        ACTIVE_NUMBER: >-
          Numbers which are already active and updated with new campaign IDs or
          service plan IDs.
      example: ACTIVE_NUMBER
      enum:
        - ACTIVE_NUMBER
  securitySchemes:
    Basic:
      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 Customer
        Dashboard](https://dashboard.sinch.com/settings/access-keys). For more
        information about basic authentication in the Numbers API, click
        [here](/docs/numbers/api-reference/authentication/basic).
    OAuth2.0:
      type: oauth2
      description: >-
        The username and password are your Key ID and Key Secret from the
        [Access keys section](https://dashboard.sinch.com/settings/access-keys)
        in the Sinch Customer Dashboard. Exchange these for a bearer token
        (access token). Learn how
        [here](/docs/numbers/api-reference/authentication/oauth).
      flows:
        clientCredentials:
          tokenUrl: https://auth.sinch.com/oauth2/token
          scopes: {}
