The Kotlin SDK

The Kotlin SDK, com.bifrostorbit:careers-sdk, shows live jobs from the delivery API, takes applications with a CV and runs the candidate portal, in Android apps and on JVM servers such as Ktor or Spring Boot. It does what the client in the JavaScript Careers SDK does, with the same errors. It is open source under the MIT licence.

• Suspend functions for Kotlin coroutines, and CompletableFutures for Java
• Built on OkHttp and kotlinx.serialization. Bring your own OkHttpClient to share its connection pool and interceptors.
• A @Serializable model for every answer

Install

It needs Java 11 or later on servers, and Android 5.0 (API 21) or later in apps. The Java futures need Android 7.0 (API 24). Kotlin projects need Kotlin 2.2 or later.

1// build.gradle.kts2dependencies {3    implementation("com.bifrostorbit:careers-sdk:0.1.0")4}

With Maven:

1<dependency>2  <groupId>com.bifrostorbit</groupId>3  <artifactId>careers-sdk</artifactId>4  <version>0.1.0</version>5</dependency>

An Android app also needs <uses-permission android:name="android.permission.INTERNET" /> in its manifest.

Set up

Create a public key under API keys. It can only read live jobs and send applications, so it may ship in an app.

1import com.bifrostorbit.careers.CareersOrbitClient23val careers = CareersOrbitClient("careers_pk_...") {4    locale = "de"5}

In Java:

CareersOrbitClient careers = CareersOrbitClient.builder("careers_pk_...")    .locale("de")    .build();

Create one client and share it. It is safe to use from many coroutines and threads at once.

Methods

1val list = careers.getJobs(JobQuery(remote = "hybrid", q = "guide"))2val job = careers.findJob("mountain-guide-lofoten") ?: return notFound()3val filters = careers.getFilters()4val site = careers.getSite()

Every call is a suspend function. Java callers use careers.async, which has the same methods and answers with CompletableFutures.

Applications

1val result = careers.apply(2    job.slug,3    CareersApplication(4        firstName = "Kari",5        lastName = "Nordmann",6        email = "kari@northwilds.com",7        privacyVersion = job.privacy.version,8        privacyAccepted = true,9        phone = "+47 912 34 567",10        answers = mapOf(11            "q-years" to CareersAnswers.number(6),12            "q-areas" to CareersAnswers.choices("lofoten", "lyngen"),13            "q-first-aid" to CareersAnswers.yesNo(true),14        ),15        source = "northwilds-app",16    ),17    CareersApplicationFiles(cv = CareersFile("kari-nordmann.pdf", cvBytes)),18)

Send the standard fields job.form asks for (job.form.asks("phone")) and an answer for each question, keyed by its id. Choice answers are option ids. privacyAccepted must be true; the client refuses the application before sending it otherwise. Files are PDF or Word documents up to 10 MB.

Candidate portal

CareersPortalClient lets candidates sign in with an emailed code and follow their applications. Keep the session token somewhere safe, such as EncryptedSharedPreferences, by implementing CareersSessionStore; CareersMemorySession keeps it in memory.

1val portal = CareersPortalClient {2    publicKey = "careers_pk_..."3    locale = "de"4    session = EncryptedSession(context)5}67portal.requestCode("solveig@northwilds.com")8portal.signIn("solveig@northwilds.com", "123456")9val me = portal.me() // null when signed out10me?.offers?.firstOrNull { it.status == "open" }?.let { offer ->11    portal.acceptOffer(offer.id, CareersOfferAcceptance("Solveig Haugen", consent = true, documentHash = offer.documentHash.orEmpty()))12}

Calls that change something answer with the whole CareersPortal again. A 401 throws CareersSignedOutException and clears the session store. Leave out publicKey when baseUrl is your own server, which adds the key. Java callers use portal.async.

Errors

Failed calls throw a CareersOrbitException, or one of its kinds. Each has the HTTP status and the API's code, and a message candidates can read in the language of the request.

Reads are retried twice after network and server errors, with back-off. Applications, sign-ups and portal changes are sent once. Cancelling the coroutine cancels the request. See Troubleshooting.