Sinch Java SDK for Numbers
The Sinch Numbers Java SDK allows you to quickly interact with the Numbers API from inside your Java applications. The fastest way to get started with the SDK is to check out our getting started guides. There you'll find all the instructions necessary to download, install, set up, and start using the SDK.
Note:
Syntax
When using the Java SDK, the code representing requests and queries sent to and responses received from the Numbers API are structured similarly to those that are sent and received using the Numbers API itself.
Note:
This guide describes the syntactical structure of the Java SDK for the Numbers API, including any differences that may exist between the API itself and the SDK. For a full reference on Numbers API calls and responses, see the Numbers API Reference.
App.java
Use this code to list available numbers.
package numbers;
import com.sinch.sdk.*;
import com.sinch.sdk.domains.numbers.models.AvailableNumber;
import com.sinch.sdk.domains.numbers.models.NumberType;
import com.sinch.sdk.domains.numbers.models.requests.AvailableNumberListAllRequestParameters;
import com.sinch.sdk.domains.numbers.models.responses.AvailableNumberListResponse;
import com.sinch.sdk.models.Configuration;
public class App {
public static void main(String[] args) {
SinchClient client = new SinchClient(Configuration.builder()
.setKeyId("YOUR_access_key")
.setKeySecret("YOUR_access_secret")
.setProjectId("YOUR_project_id")
.build());
AvailableNumberListResponse numbers = client.numbers().available().list(AvailableNumberListAllRequestParameters.builder()
.setType(NumberType.[Value])
.setRegionCode("YOUR_region_code")
.build());
for (AvailableNumber n : numbers.getContent()) {
System.out.println(n);
}
}
}The code sample on the side of this page is an example of how to use the Java SDK to list the available numbers of a given type and region. The code is also displayed below, along with a Numbers API call that accomplishes the same task, for reference:
import java.net.*;
import java.net.http.*;
import java.util.*;
public class App {
public static void main(String[] args) throws Exception {
var httpClient = HttpClient.newBuilder().build();
var host = "https://numbers.api.sinch.com";
var projectId = "YOUR_projectId";
var pathname = "/v1/projects/" + projectId + "/availableNumbers";
var request = HttpRequest.newBuilder()
.GET()
.uri(URI.create(host + pathname ))
.header("Authorization", "Basic " + Base64.getEncoder().encodeToString(("YOUR_username:YOUR_password").getBytes()))
.build();
var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}package numbers;
import com.sinch.sdk.*;
import com.sinch.sdk.domains.numbers.models.AvailableNumber;
import com.sinch.sdk.domains.numbers.models.NumberType;
import com.sinch.sdk.domains.numbers.models.requests.AvailableNumberListAllRequestParameters;
import com.sinch.sdk.domains.numbers.models.responses.AvailableNumberListResponse;
import com.sinch.sdk.models.Configuration;
public class App {
public static void main(String[] args) {
SinchClient client = new SinchClient(Configuration.builder()
.setKeyId("YOUR_access_key")
.setKeySecret("YOUR_access_secret")
.setProjectId("YOUR_project_id")
.build());
AvailableNumberListResponse numbers = client.numbers().available().list(AvailableNumberListAllRequestParameters.builder()
.setType(NumberType.*)
.setRegionCode("YOUR_region_code")
.build());
for (AvailableNumber n : numbers.getContent()) {
System.out.println(n);
}
}
}This example highlights the following required to successfully make a Numbers API call using the Sinch Java SDK:
Client
When using the Sinch Java SDK, you initialize communication with the Sinch backend by initializing the Java SDK's main client class. This client allows you to access the functionality of the Sinch Java SDK.
Initialization
To successfully initialize the Sinch client class, you must provide a valid access key ID and access key secret combination. You must also provide your Project ID. For example:
package numbers.sdk;
import com.sinch.sdk.SinchClient;
public class App {
public static String access_key = "YOUR_access_key";
public static String access_secret = "YOUR_access_secret";
public static String project_id = "YOUR_project_id"
public static void main(String[] args) {
SinchClient client = new SinchClient(Configuration.builder()
.setKeyId(access_key)
.setKeySecret(access_secret)
.setProjectId(project_id)
.build());
}Numbers domain
The Sinch Java SDK organizes different functionalities in the Sinch product suite into domains. These domains are accessible through the client. For example,client.numbers().[endpoint_category()].[method()].Endpoint categories
In the Sinch Java SDK, Numbers API endpoints are accessible through the client. The naming convention of the endpoints in the SDK resembles the API:
available()active()regions()callback()
For example:
var numbers = client.numbers().available().list(AvailableNumberListAllRequestParameters.builder()
.setType(NumberType.LOCAL)
.setRegionCode("US")
.build());The field mappings are described in the sections below.
numbers().available() endpoint category
The numbers().available() category of the Java SDK corresponds to the batches endpoint. The mapping between the API operations and corresponding Java methods are described below, as well as links to the JavaDocs page:| API operation | SDK method | JavaDocs |
|---|---|---|
| Activate a new phone number | rent() | rent |
| Search for available phone numbers | list() | list |
| Rent any available number | rentAny() | rentAny |
numbers().active() endpoint category
The numbers().active() category of the Java SDK corresponds to the activeNumbers endpoint. The mapping between the API operations and corresponding Java methods are described below, as well as links to the JavaDocs page:| API operation | SDK method | JavaDocs |
|---|---|---|
| List active numbers for a project | list() | list |
| Update active number | update() | update |
| Retrieve active number | get() | get |
| Release active number | release() | release |
numbers().regions() endpoint category
The numbers().regions() category of the Java SDK corresponds to the availableRegions endpoint. The mapping between the API operations and corresponding Java methods are described below, as well as links to the JavaDocs page:| API operation | SDK method | JavaDocs |
|---|---|---|
| List available regions | list() | list |
numbers().callback() endpoint category
The numbers().callback() category of the Java SDK corresponds to the callbackConfiguration endpoint. The mapping between the API operations and corresponding Java methods are described below, as well as links to the JavaDocs page:| API operation | SDK method | JavaDocs |
|---|---|---|
| Get callbacks configuration | get() | get |
| Update callback configuration | update() | update |
Request and query parameters
Requests and queries made using the Java SDK are similar to those made using the SMS API. Many of the fields are named and structured similarly. For example, consider the representations of an SMS API message type. One field is represented in JSON, and the other is using our Java SDK:
NumberType.MOBILE"type": "MOBILE"Many fields in the Java SDK are rendered as enums in data models.
Nested objects
When making calls directly to the API, we use JSON objects, including (in some cases) nested JSON objects. When using the Java SDK, we use Java data models instead of nested JSON objects. For example, consider the SMS configuration objects below. One is represented in JSON, the other as a Java object:
AvailableNumberListAllRequestParameters.builder()
.setType(NumberType.LOCAL)
.setRegionCode("US")
.build(){
"type": "LOCAL",
"regionCode": "US"
}builder() method to construct the appropriate data model in the correct structure.Responses
Response fields match the API responses. They are delivered as Java objects.
