Android

Learn how to get started with Citadel API for your Android application

Setup for Android

Once you have your API keys, it's time to run the Citadel Android Quickstart app locally.
Requirements: Android Studio

  1. git clone https://github.com/citadelid/quickstart-android
  2. cd quickstart-android
  3. Create a local.properties file with the following content (values with <> should be replaced by the proper keys or values):
citadelClientId="<client_id>"
citadelSecret="<access_key>"
citadelApiUrl="https://prod.citadelid.com/v1/"
citadelProductType="<employment or income>"
  1. Open the project in Android Studio and run the app

Run Quickstart

The Android Quickstart app emulates the experience of an applicant going through an employment and income verification.

After opening the Android Quickstart app you will be presented with the Citadel Bridge.

Use the Sandbox credentials to successfully connect a payroll account.

When you click "Done" at the end of Bridge you will be able to see the data returned by the Citadel API.

Step-by-step overview

This flow involves a user, the application front end, the application back end and the Citadel API. You can see a visual diagram of tokens and data exchange in Bridge section of docs.

1. Authorize and initialize Bridge

Your app sends an API request to Citadel for bridge_tokenbridge_token - A short-lived token provided by the Citadel API to authorize the use of Bridge. This token has a 6 hour expiration..

citadel.getBridgeToken { token ->
    if(token != null) {
      loadWidget(token)
    } else {
      Toast.makeText(applicationContext,"Issue with Bridge Token", Toast.LENGTH_LONG).show()
    }
  }
public fun getBridgeToken(callback: (String?) -> Unit) {
    var endpoint = "bridge-tokens/"
    VolleySingleton.getInstance(appContext).addToRequestQueue(Request.Method.POST, endpoint, null) { response ->
      if(response != null) {
        callback(response.getString("bridge_token"))
      } else {
        callback(null)
      }
    }
  }

Your app loads a mobile page from Citadel's CDN with bridge_tokenbridge_token - A short-lived token provided by the Citadel API to authorize the use of Bridge. This token has a 6 hour expiration. into native WebView.

fun loadWidget(bridgeToken: String) {
    val myWebView: WebView = findViewById(R.id.webview)
    myWebView.clearCache(true)
    myWebView.settings.javaScriptEnabled = true
    myWebView.addJavascriptInterface(JsInterface(), "citadelInterface")
    val builder: Uri.Builder = Uri.Builder()
    builder.scheme("https")
      .authority("cdn.citadelid.com")
      .appendPath("mobile.html")
      .appendQueryParameter("bridge_token", bridgeToken)
      .fragment("section-name")
    myWebView.loadUrl(builder.build().toString())
  }

2. User connects account

User selects an employer, choses their provider, logs in, and clicks Done.

@android.webkit.JavascriptInterface
  fun onSuccess(payloadJSON: String) {
    val payload = JSONObject(payloadJSON)
    val publicToken = payload.getString("public_token")
    citadel.getAccessToken(publicToken) { accessToken ->

Your app sends an API request to Citadel exchanging the temporary public_tokenpublic_token - A short-lived token used to exchange for an *access_token* from the backend. This token has a 6 hour expiration. for access_tokenaccess_token - A private token unique to a single Link. Used to access Link data and initiate any actions using the same Link.

public fun getAccessToken(publicToken: String, callback: (String?) -> Unit) {
    var endpoint = "access-tokens/"
    var body = JSONObject()
    var publicTokensArray = JSONArray()
    publicTokensArray.put(publicToken)
    body.put("public_tokens", publicTokensArray)

    VolleySingleton.getInstance(appContext).addToRequestQueue(Request.Method.POST, endpoint, body) { response ->
      if(response != null) {
        var responseArray = response.getJSONArray("access_tokens")
        callback(responseArray.getString(0))
      } else {
        callback(null)
      }
    }
  }

3. Get data from API

Your app sends an API request to Citadel with an access_tokenaccess_token - A private token unique to a single Link. Used to access Link data and initiate any actions using the same Link for employment/income verification.

public fun getEmploymentInfoByToken(accessToken: String, callback: (JSONObject?) -> Unit) {
    var endpoint = "verifications/employments/"
    var body = JSONObject()
    body.put("access_token", accessToken)

    VolleySingleton.getInstance(appContext).addToRequestQueue(Request.Method.POST, endpoint, body) { response ->
      if(response != null) {
        callback(response)
      } else {
        callback(null)
      }
    }
  }

Your app renders the data sent back by Citadel API for the user.

fun showEmploymentResults(verification: JSONObject) {
    val intent = Intent(this, DisplayEmploymentActivity::class.java).apply {
      putExtra("verification", verification.toString())
    }
    startActivity(intent)
  }

Did this page help you?