Sinch Java SDK for Verification

The Sinch Verification Java SDK allows you to quickly interact with the Verification 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.

Syntax

When using the Java SDK, the code representing requests and queries sent to and responses received from the Verification API are structured similarly to those that are sent and received using the Verification API itself.

The code sample on the side of this page is an example of how to use the Java SDK to intiate an SMS PIN Verification. The code is also displayed below, along with a Verification API call that accomplishes the same task, for reference:

package app;

import java.io.IOException;
import java.net.*;
import java.net.http.*;
import java.util.*;

public class App {
    
    private static final String applicationKey = "<REPLACE_WITH_VERIF_APP_KEY>";
    private static final String applicationSecret = "<REPLACE_WITH_VERIF_APP_SECRET>";
    private static final String toNumber = "<REPLACE_WITH_TO_NUMBER>";
    private static final String SINCH_URL = "https://verification.api.sinch.com/verification/v1/verifications";
    public static final String JSON_CONTENT_TYPE = "application/json; charset=utf-8";
    
    public static void main(String[] args) throws Exception {
        
        HttpResponse<String> response = sendSMSPinWithBasicAuth();

        System.out.println(response.body());
    }

    private static HttpResponse<String> sendSMSPinWithBasicAuth() throws IOException, InterruptedException {
        var httpClient = HttpClient.newBuilder().build();

        var payload = getSMSVerificationRequestBody();

        var request = HttpRequest.newBuilder()
                .POST(HttpRequest.BodyPublishers.ofString(payload))
                .uri(URI.create(SINCH_URL))
                .header("Content-Type", JSON_CONTENT_TYPE)
                .header("Authorization", "Basic " + Base64.getEncoder().encodeToString((applicationKey + ":" + applicationSecret).getBytes()))
                .build();

        return httpClient.send(request, HttpResponse.BodyHandlers.ofString());
    }

    private static String getSMSVerificationRequestBody() {
        return """
            {
                "identity": {
                    "type": "number",
                    "endpoint": "%s"
                },
                "method": "sms"
            }
            """.formatted(toNumber);
    }
}

package verification;

import com.sinch.sdk.domains.verification.api.v1.VerificationService;
import com.sinch.sdk.domains.verification.api.v1.VerificationStartService;
import com.sinch.sdk.domains.verification.models.v1.NumberIdentity;
import com.sinch.sdk.domains.verification.models.v1.start.request.VerificationStartRequestSms;
import com.sinch.sdk.domains.verification.models.v1.start.response.VerificationStartResponseSms;
import java.util.logging.Logger;

public class Snippet {

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

  static void execute(VerificationService verificationService) {

    // REMINDER: verification Service require to have set application key/secret
    // onto Sinch Client init
    VerificationStartService startService = verificationService.verificationStart();

    String phoneNumber = "YOUR_phone_number";

    LOGGER.info(String.format("Sending a SMS verification to '%s'", phoneNumber));

    VerificationStartResponseSms response =
        startService.startSms(
            VerificationStartRequestSms.builder()
                .setIdentity(NumberIdentity.valueOf(phoneNumber))
                .build());

    LOGGER.info("Response: " + response);
  }
}

This example highlights the following required to successfully make a Verification API call using the Sinch Java SDK:

• Client initialization
• Verification domain
• Endpoint usage
• Field population

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 start using the SDK, you need to initialize the main client class and create a configuration object to connect to your Sinch account and Verification app. You can find all of the credentials you need on your Sinch dashboard.

import com.sinch.sdk.SinchClient;
import com.sinch.sdk.models.Configuration;

public class App {
    
    public static void main(String[] args) {
        SinchClient client = new SinchClient(Configuration.builder()
                                    .setApplicationKey("YOUR_application_key")
                                    .setApplicationSecret("YOUR_application_secret")
                                    .build());
    }
}

Verification domain

Endpoint categories

In the Sinch Java SDK, Verification API endpoints are accessible through the client. The naming convention of the endpoints represented in the SDK matches the API:

• verification().v1().verificationStart()
• verification().v1().verificationReport()
• verification().v1().verificationStatus()
• verification().v1().webhooks()

For example:

var identity = NumberIdentity.valueOf("YOUR_phone_number");
var response = client.verification().v1().verificationStart().startSms(VerificationStartRequestSms
                                        .builder()
                                        .setIdentity(identity)
                                        .build());

The field mappings are described in the sections below.

verification().v1().verificationStart() endpoint category

verification().v1().verificationReport() endpoint category

verification().v1().verificationStatus() endpoint category

verification().v1().webhooks() endpoint category

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 a Verification method type. One field is represented in JSON, and the other is using our Java SDK:

VerificationStartRequestSms

"method": "sms"

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 Verification configuration objects below. One is represented in JSON, the other as a Java object:

VerificationStartRequestSms.builder()
                                .setIdentity(NumberIdentity.builder()
                                    .setEndpoint("YOUR_phone_number")
                                    .build())
                                .build()

{
  "method": "sms",
  "identity": {
    "type": "number",
    "endpoint": "YOUR_phone_number"
  }
}

Responses

Response fields match the API responses. They are delivered as Java objects.