Add e-signatures
to a Kotlin app

Add OkHttp for HTTP, Gson for JSON, and Kotlin coroutines. These three libraries cover everything the GetSigned integration needs — no dedicated SDK required.

// build.gradle.kts
dependencies {
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
    implementation("com.google.code.gson:gson:2.10.1")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.1")
}

Exchange your client credentials for a bearer token. The token is valid for 3600 seconds — cache it in memory and refresh when it expires.

import okhttp3.*
import com.google.gson.Gson
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext

private val gson = Gson()
private val http = OkHttpClient()

data class TokenResponse(val access_token: String, val expires_in: Int)

suspend fun getToken(clientId: String, clientSecret: String): String =
    withContext(Dispatchers.IO) {
        val body = FormBody.Builder()
            .add("grant_type",    "client_credentials")
            .add("client_id",     clientId)
            .add("client_secret", clientSecret)
            .build()
        val req = Request.Builder()
            .url("https://api.getsigned.app/oauth/token")
            .post(body)
            .build()
        http.newCall(req).execute().use { res ->
            gson.fromJson(res.body!!.string(), TokenResponse::class.java).access_token
        }
    }

Upload the PDF as a multipart form request alongside signers and field coordinates. The API returns an envelope ID you use to send the document.

import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody

data class EnvelopeResponse(val id: String, val status: String)

suspend fun createEnvelope(
    token:    String,
    pdfBytes: ByteArray,
    signerName:  String,
    signerEmail: String,
): String = withContext(Dispatchers.IO) {
    val multipart = MultipartBody.Builder()
        .setType(MultipartBody.FORM)
        .addFormDataPart(
            "document", "contract.pdf",
            pdfBytes.toRequestBody("application/pdf".toMediaType())
        )
        .addFormDataPart("signers",
            """[{"name":"$signerName","email":"$signerEmail"}]""")
        .addFormDataPart("fields",
            """[{"type":"signature","page":1,"x":300,"y":580,"w":200,"h":60}]""")
        .build()

    val req = Request.Builder()
        .url("https://api.getsigned.app/v1/envelopes")
        .header("Authorization", "Bearer $token")
        .post(multipart)
        .build()

    http.newCall(req).execute().use { res ->
        gson.fromJson(res.body!!.string(), EnvelopeResponse::class.java).id
    }
}

Calling /send dispatches the signing link. When the signer completes, GetSigned POSTs to your webhook. Verify the HMAC-SHA256 signature before processing.

import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
import java.security.MessageDigest

suspend fun sendEnvelope(token: String, envelopeId: String) =
    withContext(Dispatchers.IO) {
        val req = Request.Builder()
            .url("https://api.getsigned.app/v1/envelopes/$envelopeId/send")
            .header("Authorization", "Bearer $token")
            .post("".toRequestBody())
            .build()
        http.newCall(req).execute().close()
    }

// In your webhook handler (Ktor / Spring Boot):
fun verifyHmac(rawBody: ByteArray, sigHeader: String, secret: String): Boolean {
    val mac = Mac.getInstance("HmacSHA256")
    mac.init(SecretKeySpec(secret.toByteArray(Charsets.UTF_8), "HmacSHA256"))
    val computed = mac.doFinal(rawBody)
        .joinToString("") { "%02x".format(it) }
    // MessageDigest.isEqual is constant-time — don't use String.equals() here
    return MessageDigest.isEqual(
        computed.toByteArray(Charsets.UTF_8),
        sigHeader.toByteArray(Charsets.UTF_8),
    )
}

// envelope.completed → download sealed PDF:
// GET /v1/envelopes/{id}/document
//   Authorization: Bearer $TOKEN