Truecaller SDK

https://docs.truecaller.com/truecaller-sdk
Admin
Truecaller SDK is a mobile number verification service that allows developers to quickly verify,...
Tokens:32,875
Snippets:312
Trust Score:10
Update:8 months ago
Show doc for...
Tokens:
Raw
### Setup TruecallerSDK with App Credentials in Swift

Source: https://docs.truecaller.com/truecaller-sdk/ios/integrating-with-your-ios-app/usage/swift

Check device compatibility and set up the Truecaller SDK using your application key and link. This should ideally be done during application launch. Ensure correct values for YOUR_APP_KEY and YOUR_APP_LINK.

```swift
//Setup TruecallerSDK
if TCTrueSDK.sharedManager().isSupported() {
    TCTrueSDK.sharedManager().setupWithAppKey(<#YOUR_APP_KEY#>, appLink:  <#YOUR_APP_LINK#>)
}
```

```swift
//Setup TruecallerSDK
if TCTrueSDK.sharedManager().isSupported() {
    TCTrueSDK.sharedManager().setup(withAppKey: <#YOUR_APP_KEY#>, appLink: <#YOUR_APP_LINK#>)
}
```

--------------------------------

### Install Truecaller SDK with CocoaPods

Source: https://docs.truecaller.com/truecaller-sdk/ios/integrating-with-your-ios-app/setup

Integrates the Truecaller SDK into an Xcode project using CocoaPods. This method automates dependency management. Ensure you have CocoaPods installed and a Podfile in your project directory.

```ruby
platform :ios, '8.0'
use_frameworks!

target 'TargetName' do
pod 'TrueSDK'
end
```

--------------------------------

### Check Device Support and Setup TruecallerSDK in Objective-C

Source: https://docs.truecaller.com/truecaller-sdk/ios/integrating-with-your-ios-app/usage/objective-c

Before initializing the Truecaller SDK, check if the current device supports it using `isSupported`. If supported, set up the SDK with your application key and link. This is typically done during application launch.

```objectivec
if ([[TCTrueSDK sharedManager] isSupported]) {
    [[TCTrueSDK sharedManager] setupWithAppKey:<#YOUR_APP_KEY#> appLink:<#YOUR_APP_LINK#>];
}
```

--------------------------------

### Configure Java Compatibility (Gradle)

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/setup

This code snippet configures the Java compatibility for your Android project to version 1.8. This is often required by SDKs to ensure proper functionality and is added to the android block in your app-level build.gradle file.

```gradle
android{
    compileOptions{
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}
```

--------------------------------

### Add mavenCentral() Repository (Gradle)

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/setup

This snippet demonstrates how to add the mavenCentral() repository to your project-level build.gradle file. This repository is crucial for resolving dependencies, including the Truecaller SDK. It should be placed within the allprojects block.

```gradle
allprojects{
    repositories{
        ...
        mavenCentral()
        ...
    }
}
```

--------------------------------

### Add Truecaller SDK Dependency (Gradle)

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/setup

This snippet shows how to add the Truecaller SDK dependency to your app-level build.gradle file. Ensure you are using version 3.2.0 or a later compatible version. This dependency enables OAuth functionality.

```gradle
dependencies {
    ...
    implementation "com.truecaller.android.sdk:truecaller-sdk:3.2.0"
}
```

--------------------------------

### Create TcSdkOptions with Default Settings (Kotlin)

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/initialisation

This code snippet shows how to create a `TcSdkOptions` object using the default SDK settings. It bypasses all customization options and directly calls the `build()` method on the `Builder`.

```kotlin
val tcSdkOptions = TcSdkOptions.Builder(this, tcOAuthCallback).build()
```

--------------------------------

### Create TcSdkOptions with Customizations (Kotlin)

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/initialisation

This snippet demonstrates how to create a `TcSdkOptions` object with various customization settings. It uses the `Builder` pattern and allows for configuring button colors, text, shape, consent title, and SDK options. The `build()` method finalizes the options object.

```kotlin
val tcSdkOptions = TcSdkOptions.Builder(this, tcOAuthCallback)
.buttonColor(Color.parseColor("<<VALID_COLOR_HEX_CODE>>"))
.buttonTextColor(Color.parseColor("<<VALID_COLOR_HEX_CODE>>"))
.loginTextPrefix(TcSdkOptions.LOGIN_TEXT_PREFIX_TO_GET_STARTED)
.ctaText(TcSdkOptions.CTA_TEXT_CONTINUE)
.buttonShapeOptions(TcSdkOptions.BUTTON_SHAPE_ROUNDED)
.footerType(TcSdkOptions.FOOTER_TYPE_SKIP)
.consentTitleOption(TcSdkOptions.SDK_CONSENT_TITLE_LOG_IN)
.sdkOptions(TcSdkOptions.OPTION_VERIFY_ONLY_TC_USERS)
.build();
```

--------------------------------

### Initialize Truecaller SDK in Background Thread (Kotlin)

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/initialisation

This snippet demonstrates the recommended way to initialize the Truecaller SDK. It uses coroutines (`launch` and `withContext`) to perform the `TcSdk.init()` operation on an IO dispatcher (background thread) to avoid blocking the main thread. After initialization, `TcSdk.getInstance()` can be accessed.

```kotlin
launch {
  withContext(Dispatchers.IO) {
     TcSdk.init(tcSdkOptions)
   }
// Now can access TcSdk.getInstance()
}
```

--------------------------------

### Import TruecallerSDK Framework in Swift

Source: https://docs.truecaller.com/truecaller-sdk/ios/integrating-with-your-ios-app/usage/swift

Import the TruecallerSDK framework at the beginning of your Swift class to enable its functionalities. This is required in classes where you initialize the SDK or handle profile responses.

```swift
import TrueSDK
```

--------------------------------

### Example Error Responses from Truecaller API

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/non-truecaller-user-verification/server-side-validation

These examples show potential error responses from the Truecaller API. This includes invalid partner credentials (404), invalid access token (1404), and internal server errors (500).

```json
{
    "code":404,
    "message":"Invalid partner credentials."
}
```

```json
{
    "code":1404,
    "message":"Invalid access token."
}
```

```json
{
    "code":500,
    "message":"error message"
}
```

--------------------------------

### Override Library for Lower SDK Versions (AndroidManifest.xml)

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/setup

This XML snippet provides a way to override the library for SDK versions below API level 24. This ensures the Truecaller SDK functions correctly for API level 24 and above, while gracefully disabling itself for older versions, preventing compilation issues.

```xml
<uses-sdk tools:overrideLibrary="com.truecaller.android.sdk"/>
```

--------------------------------

### Example Successful Response from Truecaller API

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/non-truecaller-user-verification/server-side-validation

This is an example of a successful response (200 OK) from the Truecaller API when an access token is valid. It returns the user's phone number and country code.

```json
{
    "phoneNumber":919999XXXXX9,
    "countryCode":"IN"
}
```

--------------------------------

### Track Truecaller User Verification Requests (Android)

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/instrumentation

Implement tracking for users who have the Truecaller app installed. This involves monitoring the invocation of `TcSdk.getInstance().isOAuthFlowUsable` for verification requests and observing `onSuccess` and `onFailure` callbacks for successful verifications or errors.

```java
```java
// Invocation for verification request
TcSdk.getInstance().isOAuthFlowUsable(this, requestCode);

// Success callback
@Override
public void onSuccess(TcOAuthData response) {
    // Track successful verification
}

// Failure callback
@Override
public void onFailure(TcOAuthError error) {
    // Track verification errors
}
```
```

--------------------------------

### Register URL Scheme for Error Handling (SDK v0.1.7+)

Source: https://docs.truecaller.com/truecaller-sdk/ios/integrating-with-your-ios-app/configuration

Starting with SDK version 0.1.7, it's mandatory to register a URL scheme in the format 'truecallersdk-<YOUR_APP_KEY>' to receive error details when redirection from the Truecaller app fails. For example, if your app key is I7ViZ490028736bba408881687123b4cec49f, the URL scheme should be truecallersdk-I7ViZ490028736bba408881687123b4cec49f.

```text
truecallersdk-<YOUR_APP_KEY>
```

--------------------------------

### Check OAuth Flow Usability (Kotlin)

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/initialisation

This code snippet shows how to check if the OAuth functionality of the Truecaller SDK is usable after initialization. It retrieves the SDK instance using `TcSdk.getInstance()` and accesses the `isOAuthFlowUsable` property. If this returns false, a fallback mechanism should be used.

```kotlin
val isUsable = TcSdk.getInstance().isOAuthFlowUsable
```

--------------------------------

### Get User Profile

Source: https://docs.truecaller.com/truecaller-sdk/mobile-websites/integrating-with-your-mobile-website/fetch-user-profile

This endpoint allows you to retrieve the user's profile information by making a GET request with an authorization token.

```APIDOC
## GET /v1/default

### Description
Fetches the user's profile information from Truecaller.

### Method
GET

### Endpoint
https://profile4-noneu.truecaller.com/v1/default

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Bearer token for authentication. Example: `Bearer YOUR_ACCESS_TOKEN`
- **Cache-Control** (string) - Optional - Set to `no-cache`.

### Request Example
```bash
curl -X GET \
  -H "Authorization: Bearer a3sAB0KnGANg4VZwIXfhUyFmPbzoONofl4FjIItac0JQSODp6niW8oBr33uOI-u7" \
  -H "Cache-Control: no-cache" \
  "https://profile4-noneu.truecaller.com/v1/default"
```

### Response
#### Success Response (200)
- **phoneNumbers** (array of strings) - The user's phone numbers.
- **addresses** (array of objects) - The user's addresses.
  - **countryCode** (string) - Country code.
  - **city** (string) - City name.
  - **street** (string) - Street name.
  - **zipcode** (string) - Zip code.
- **avatarUrl** (string) - URL of the user's avatar.
- **aboutMe** (string) - A short description about the user.
- **jobTitle** (string) - The user's job title.
- **companyName** (string) - The name of the user's company.
- **history** (object) - Information about profile updates.
  - **name** (object) - Details about name updates.
    - **updateTime** (string) - Timestamp of the last name update.
- **isActive** (string) - Indicates if the user profile is active.
- **gender** (string) - The user's gender.
- **createdTime** (string) - Timestamp when the profile was created.
- **onlineIdentities** (object) - User's online identities.
  - **url** (string) - URL of the user's website.
  - **email** (string) - User's email address.
  - **facebookId** (string) - User's Facebook ID.
- **type** (string) - Type of the profile (e.g., 'Personal').
- **id** (string) - Unique identifier for the profile.
- **userId** (string) - The user's Truecaller ID.
- **badges** (array of strings) - Badges associated with the user's profile (e.g., 'verified', 'premium').
- **name** (object) - The user's name.
  - **last** (string) - User's last name.
  - **first** (string) - User's first name.

#### Response Example
```json
{
  "phoneNumbers": ["919999999999"],
  "addresses": [
    {
       "countryCode": "in",
       "city": "city_field_value",
       "street": "street_field_value",
       "zipcode": "1234567"
    }
  ], 
  "avatarUrl": "https://s3-eu-west-1.amazonaws.com/images1.truecaller.com/myview/1/15a999e9806gh73834c87aaa0498020d/3", 
  "aboutMe":"About me",
  "jobTitle": "CEO", 
  "companyName": "ABC",  
  "history": {
    "name": 
    {
      "updateTime": "1508089888000"
    }
  },
  "isActive": "True", 
  "gender": "Male", 
  "createdTime": "1379314068000", 
  "onlineIdentities": {
    "url": "https://www.truecaller.com", 
    "email": "y.s@truecaller.com",
    "facebookId":"105056625245"
  },
  "type": "Personal", 
  "id": "655574719", 
  "userId":"1319413476",
  "badges": ["verified", "premium"],
  "name": {
    "last": "Kapoor", 
    "first": "Rajat"
  }
}
```

#### Error Responses
- **401 Unauthorised**: If your credentials are not valid.
- **5xx Server error**: Any other server-side error.
```

--------------------------------

### Import TruecallerSDK Framework in Objective-C

Source: https://docs.truecaller.com/truecaller-sdk/ios/integrating-with-your-ios-app/usage/objective-c

Import the TruecallerSDK framework into your Objective-C class. This is necessary for using any of the SDK's functionalities, such as initialization and receiving profile data.

```objectivec
#import <TrueSDK/TrueSDK.h>
```

--------------------------------

### Handle User Activity for TruecallerSDK in AppDelegate (Swift)

Source: https://docs.truecaller.com/truecaller-sdk/ios/integrating-with-your-ios-app/usage/swift

Implement the `application(application: continueUserActivity: restorationHandler:)` method in your AppDelegate to allow TruecallerSDK to handle user activities. This ensures seamless integration with the Truecaller flow.

```swift
func application(application: UIApplication, continueUserActivity userActivity: NSUserActivity, restorationHandler: ([AnyObject]?) -> Void) -> Bool {
    return TCTrueSDK.sharedManager().application(application, continueUserActivity: userActivity, restorationHandler: restorationHandler)
}
```

```swift
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Swift.Void) -> Bool {
    return TCTrueSDK.sharedManager().application(application, continue: userActivity, restorationHandler: restorationHandler)
}
```

```swift
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    return TCTrueSDK.sharedManager().application(application, continue: userActivity, restorationHandler: restorationHandler as? ([Any]?) -> Void)
}
```

--------------------------------

### GET /v1/userinfo

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/integrating-with-your-backend/fetching-user-profile

Fetches the user's profile information using an access token. The response details depend on the scopes granted by the user during authentication.

```APIDOC
## GET /v1/userinfo

### Description
Fetches the user's profile information using an access token. The response details depend on the scopes granted by the user during authentication.

### Method
GET

### Endpoint
https://oauth-account-noneu.truecaller.com/v1/userinfo

### Parameters
#### Headers
- **Authorization** (string) - Required - "Bearer <ACCESS_TOKEN>"

### Request Example
```curl
curl --location --request GET 'https://oauth-account-noneu.truecaller.com/v1/userinfo' \
--header 'Authorization: Bearer testtoken'
```

### Response
#### Success Response (200)
- **sub** (string) - User's unique identifier.
- **given_name** (string) - User's first name.
- **family_name** (string) - User's last name.
- **phone_number** (string) - User's phone number.
- **email** (string) - User's email address.
- **picture** (string) - URL to the user's profile picture.
- **gender** (string) - User's gender.
- **phone_number_country_code** (string) - Country code for the phone number.
- **phone_number_verified** (boolean) - Indicates if the phone number is verified.
- **address** (object) - User's address information.
  - **locality** (string) - City or locality.
  - **postal_code** (string) - Postal code.

#### Response Example
```json
{
  "sub": "13627101294235520",
  "given_name": "xyz",
  "family_name": "xyz",
  "phone_number": "91xxxxxxxxxx",
  "email": "<pqr@gmail.com>",
  "picture": "<https://www.truecaller.com/xyz>",
  "gender": "male/female",
  "phone_number_country_code": "IN",
  "phone_number_verified": true,
  "address": {
    "locality": "Bangalore",
    "postal_code": "5xxxxx"
  }
}
```

#### Error Responses
- **401: Unauthorized** - If authentication type is not bearer token or token is invalid/expired.
- **404: Not Found** - Profile information is not present for the user.
- **422: Unprocessable Entity** - openid scope missing in initial request.
- **500: Internal Server Error** - Failed to validate token due to server error or unexpected error at the server side.
```

--------------------------------

### Initiate User Verification via OTP

Source: https://docs.truecaller.com/truecaller-sdk/ios/integrating-with-your-ios-app/verifying-non-truecaller-app-users

Start the verification process for a given phone number and country code. This method triggers the SMS-based OTP flow for users not on Truecaller.

```swift
TCTrueSDK.sharedManager().requestVerification(forPhone: <#PHONE_NUMBER_STRING>, countryCode: <#DEFAULT_COUNTRY_CODE>)
```

```objectivec
[[TCTrueSDK sharedManager] requestVerificationForPhone:<#PHONE_NUMBER_STRING> countryCode:<#DEFAULT_COUNTRY_CODE>];
```

--------------------------------

### Handle User Activity for TruecallerSDK in Objective-C

Source: https://docs.truecaller.com/truecaller-sdk/ios/integrating-with-your-ios-app/usage/objective-c

Implement the `application:continueUserActivity:restorationHandler:` method in your AppDelegate. This method is crucial for handling the user activity initiated by the Truecaller SDK. If the SDK does not need to handle the activity, it will return false, allowing your app to manage it.

```objectivec
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray *restorableObjects))restorationHandler {
    return [[TCTrueSDK sharedManager] application:application continueUserActivity:userActivity restorationHandler:restorationHandler];
}
```

--------------------------------

### Handle User Activity for TruecallerSDK in SceneDelegate (Swift)

Source: https://docs.truecaller.com/truecaller-sdk/ios/integrating-with-your-ios-app/usage/swift

If your application uses SceneDelegate, implement the `scene(_:continue:)` method to forward user activity to the TruecallerSDK. This is crucial for handling Truecaller-related deep links and activities in modern iOS architectures.

```swift
func scene(_ scene: UIScene,
                        continue userActivity: NSUserActivity) {
        TCTrueSDK.sharedManager().scene(scene, continue: userActivity)
    }
```

--------------------------------

### Configure TCProfileRequestButton Styles

Source: https://docs.truecaller.com/truecaller-sdk/ios/integrating-with-your-ios-app/usage/swift

Configures the appearance of the TCProfileRequestButton, including its style and corner radius. This example demonstrates setting the button style to blue and the corners to rounded for both Swift 2.3 and Swift 3+.

```swift
self.button.buttonStyle = TCButtonStyleBlue
self.button.buttonCornersStyle = TCButtonCornersStyleRounded
```

```swift
self.button.buttonStyle = TCButtonStyle.blue.rawValue
self.button.buttonCornersStyle = TCButtonCornersStyle.rounded.rawValue
```

--------------------------------

### Configure Terms of Service URL

Source: https://docs.truecaller.com/truecaller-sdk/mobile-websites/integrating-with-your-mobile-website/initialisation

Specifies the URL for the terms of service, which will be displayed on the verification screen. The URL should be URL-safe.

```url
termsUrl="<<YOUR_TERMS_OF_SERVICE_LINK>>"
```

--------------------------------

### Manually Request True Profile

Source: https://docs.truecaller.com/truecaller-sdk/ios/integrating-with-your-ios-app/usage/swift

Manually requests the Truecaller profile data. This method should not be used if TCProfileRequestButton is already implemented, as it would result in duplicate requests. Examples are provided for Swift 2.3 and Swift 3+.

```swift
TCTrueSDK.sharedManager().requestTrueProfile()
```

```swift
TCTrueSDK.sharedManager().requestTrueProfile()
```

--------------------------------

### Generate and Set Code Challenge (Kotlin)

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/setting-up-oauth-parameters

Generates a code challenge from a previously generated code verifier using `CodeVerifierUtil.getCodeChallenge()`. It then sets this code challenge in the Truecaller SDK instance. Includes a null-safe check as the method might return null if SHA-256 or Base64 encoding is not supported.

```kotlin
val codeChallenge = CodeVerifierUtil.getCodeChallenge(codeVerifier)
codeChallenge?.let {
                TcSdk.getInstance().setCodeChallenge(it)
} ?: print("Code challenge is Null. Can’t proceed further")
```

--------------------------------

### Configure Truecaller Client ID (AndroidManifest.xml)

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/setup

This XML snippet shows how to declare the Truecaller Client ID as a meta-data tag within the application element of your AndroidManifest.xml file. The value should reference a string resource named 'clientID' defined in your strings.xml.

```xml
<application android:label="@string/app_name" ...>
...
<meta-data android:name="com.truecaller.android.sdk.ClientId" android:value="@string/clientID"/>
...
</application>
```

--------------------------------

### Initiate Truecaller Verification via Deep Link

Source: https://docs.truecaller.com/truecaller-sdk/mobile-websites/integrating-with-your-mobile-website/initialisation

This code snippet demonstrates how to trigger the Truecaller verification process by setting the window location to a specific deep link URL. It includes essential parameters like requestNonce, partnerKey, and partnerName, along with optional parameters for customization.

```javascript
window.location = "truecallersdk://truesdk/web_verify?type=btmsheet
                           requestNonce=UNIQUE_REQUEST_ID
                           &partnerKey=YOUR_APP_KEY
                           &partnerName=YOUR_APP_NAME
                           &lang=LANGUAGE_LOCALE
                           &privacyUrl=LINK_TO_YOUR_PRIVACY_PAGE
                           &termsUrl=LINK_TO_YOUR_TERMS_PAGE
                           &loginPrefix=TITLE_STRING_PREFIX
                           &loginSuffix=TITLE_STRING_SUFFIX
                           &ctaPrefix=BUTTON_TEXT_PREFIX
                           &ctaColor=BUTTON_FILL_COLOR
                           &ctaTextColor=BUTTON_TEXT_COLOR
                           &btnShape=BUTTON_SHAPE
                           &skipOption=FOOTER_CTA_STRING
                           &ttl=TIME_IN_MILLISECONDS";
```

--------------------------------

### Generate and Store Code Verifier (Kotlin)

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/setting-up-oauth-parameters

Generates a unique code verifier string using the `CodeVerifierUtil.generateRandomCodeVerifier()` utility. This verifier is stored in the session and will be required later for generating an access token.

```kotlin
codeVerifier = CodeVerifierUtil.generateRandomCodeVerifier()
```

--------------------------------

### App Key Generation and Usage

Source: https://docs.truecaller.com/truecaller-sdk/mobile-websites/generating-app-key

This section details the process of generating an app key from the Truecaller developer account and its importance for authenticating requests. It also outlines the requirements for the callback URL, including the request method, response time, and security considerations.

```APIDOC
## App Key Generation and Usage

### Description
To ensure the authenticity of interactions between your web app and Truecaller, you need to generate an app key (partner key) from the Truecaller developer account. This key is essential for authorizing all verification requests.

### Generating an App Key
1. Navigate to the Truecaller developer account dashboard (<https://developer.truecaller.com/login>).
2. Go to the 'MANAGE APPS' section.
3. Click on 'CREATE APP'.
4. Select 'Web' as the App type.
5. Enter your app details, including app name, domain, and a callback URL.

### Callback URL Requirements
- **Method:** All access token requests will be submitted as POST requests.
- **Asynchronous Service:** Your service must be asynchronous, as Truecaller only expects the message to be accepted.
- **Response Time:** The service should respond within a maximum of 3 seconds.
- **Security:** Use HTTPS with a valid certificate.

### Callback Request Parameters

#### Request Body Parameters

- **requestId** (String) - Mandatory - Unique identifier for the request.
- **accessToken** (String) - Mandatory - Access token provided by Truecaller.

### Expected Response Codes

- **2xx OK**: Indicates a successful response.

Once your app is created, you will receive a unique 'appKey' that must be included in your project to authorize all verification requests.
```

--------------------------------

### Truecaller SDK Deep Link Customization

Source: https://docs.truecaller.com/truecaller-sdk/mobile-websites/integrating-with-your-mobile-website/initialisation

This section details the various parameters available for customizing the Truecaller verification screen via deep links.

```APIDOC
## Truecaller SDK Deep Link Parameters

### Description
This document outlines various parameters that can be used in deep links to customize the appearance and behavior of the Truecaller verification screen.

### Parameters

#### `loginSuffix` Parameter
This parameter specifies the value for login-related actions.

| String                      | `loginSuffix` parameter value |
| --------------------------- | --------------------------------- |
| please login                | login                             |
| please signup               | signup                            |
| please login/ signup        | loginsignup                       |
| please register             | register                          |
| please sign in              | signin                            |
| please verify mobile number | verifymobile                      |

#### `skipOption` Parameter
This parameter enables you to add an optional footer string on the verification screen. Clicking this allows users to proceed to an alternate verification flow.

| Footer CTA string to use | `skipOption` parameter value |
| ------------------------ | ---------------------------- |
| Use another number       | useanothernum                |
| Use another method       | useanothermethod             |
| Enter details manually   | manualdetails                |
| Later                    | later                        |

#### `ctaPrefix` Parameter
This parameter lets you choose the prefix string for the contextual text on the CTA button.

| Button text to use | `ctaPrefix` parameter value |
| ---------------------- | --------------------------- |
| Use                    | use                         |
| Continue with          | continuewith                |
| Proceed with           | proceedwith                 |

#### `btnShape` Parameter
This parameter lets you choose the shape of the CTA button.

| Button shape | `btnShape` parameter value |
| ------------ | -------------------------- |
| Round        | round                      |
| Rectangle    | rect                       |

#### `ctaColor` Parameter
Configure the hex code to customize the color of the CTA button on the verification screen.

**Example:**
```
ctaColor=%23f75d34
```

#### `ctaTextColor` Parameter
Configure the hex code to customize the color of the text on the CTA button on the verification screen.

**Example:**
```
ctaTextColor=%23f75d34
```

**Note:** For using hex codes in deep link parameters, prepend **%23** to your hex code (e.g., `#F75D34` becomes `%23f75d34`).

#### `privacyUrl` Parameter
Add your privacy policy link (URL safe) to the verification screen.

**Example:**
```
privacyUrl="<<YOUR_PRIVACY_POLICY_LINK>>"
```

#### `termsUrl` Parameter
Add your terms of service link (URL safe) to the verification screen.

**Example:**
```
termsUrl="<<YOUR_TERMS_OF_SERVICE_LINK>>"
```

#### `ttl` (Timeout) Parameter
This parameter allows you to automatically dismiss the consent screen by adding a TTL (Time To Live) value to the deep link.

*   **Default Minimum:** 8000ms (8s). If a value less than 8000ms is provided, it defaults to 8000ms.
*   **Maximum Value:** No maximum limit.
*   **Units:** Milliseconds.
*   **Behavior without `ttl`:** The consent dialog persists indefinitely.

**Note:** TTL-based auto-dismiss functionality works if the end-user has the Truecaller app installed.

**Example:**
```
ttl=15000
```

### Request Example
```json
{
  "deeplink": "https://example.com?loginSuffix=login&skipOption=later&ctaPrefix=continuewith&btnShape=round&ctaColor=%23f75d34&ctaTextColor=%23ffffff&privacyUrl=https://example.com/privacy&termsUrl=https://example.com/terms&ttl=10000"
}
```

### Response

#### Success Response (200)
This API does not return a response body. The parameters are used to construct a deep link that modifies the verification screen behavior.

#### Response Example
N/A
```

--------------------------------

### Set OAuth Scopes (Kotlin)

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/setting-up-oauth-parameters

Sets the list of scopes to be requested from the user. The available scopes include 'profile', 'phone', 'openid', 'offline_access', 'email', and 'address'. Ensure requested scopes are enabled for your project in the Truecaller portal.

```kotlin
TcSdk.getInstance().setOAuthScopes(arrayOf("profile", "phone", ...))
```

--------------------------------

### Verify Access Token with Truecaller API (GET Request)

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/non-truecaller-user-verification/server-side-validation

This snippet demonstrates how to make a GET request to the Truecaller API endpoint to verify an access token. It requires a clientId in the header and the accessToken in the path. The response includes the user's phoneNumber and countryCode if the token is valid.

```http
GET "https://sdk-otp-verification-noneu.truecaller.com/v1/otp/client/installation/phoneNumberDetail/{accessToken}" \
  --header "clientId: YOUR_CLIENT_ID"
```

--------------------------------

### Configure Privacy Policy URL

Source: https://docs.truecaller.com/truecaller-sdk/mobile-websites/integrating-with-your-mobile-website/initialisation

Specifies the URL for the privacy policy, which will be displayed on the verification screen. The URL should be URL-safe.

```url
privacyUrl="<<YOUR_PRIVACY_POLICY_LINK>>"
```

--------------------------------

### GET /v1/otp/client/installation/phoneNumberDetail/{accessToken}

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/non-truecaller-user-verification/server-side-validation

Verifies the authenticity of an access token and retrieves the associated phone number and country code.

```APIDOC
## GET /v1/otp/client/installation/phoneNumberDetail/{accessToken}

### Description
Verifies the authenticity of an access token received from the Truecaller SDK and retrieves the associated phone number and country code. This API call should be made from your server to Truecaller's server.

### Method
GET

### Endpoint
`https://sdk-otp-verification-noneu.truecaller.com/v1/otp/client/installation/phoneNumberDetail/{accessToken}`

### Parameters
#### Header Parameters
- **clientId** (string) - Required - Your unique Client ID provided by Truecaller.

#### Path Parameters
- **accessToken** (string) - Required - The token granted for the partner for the respective user number that initiated login.

### Request Example
```json
{
  "headers": {
    "clientId": "zHTqS70ca9d3e016946f19a65b01dRR5e56460"
  },
  "pathParameters": {
    "accessToken": "71d8367e-39f7-4de5-a3a3-2066431b9ca8"
  }
}
```

### Response
#### Success Response (200 OK)
- **phoneNumber** (integer) - The verified phone number.
- **countryCode** (string) - The country code associated with the phone number (e.g., "IN").

#### Response Example (200 OK)
```json
{
    "phoneNumber": 919999XXXXX9,
    "countryCode": "IN"
}
```

#### Error Responses
- **404 Not Found** - If your credentials are not valid.
  ```json
  {
      "code": 404,
      "message": "Invalid partner credentials."
  }
  ```
- **404 Not Found** - If the access token is invalid.
  ```json
  {
      "code": 1404,
      "message": "Invalid access token."
  }
  ```
- **500 Internal Error** - For any other internal server errors.
  ```json
  {
      "code": 500,
      "message": "error message"
  }
  ```
```

--------------------------------

### Get Access Token

Source: https://docs.truecaller.com/truecaller-sdk/ios/integrating-with-your-ios-app/verifying-non-truecaller-app-users/completing-verification

Retrieves an access token that can be used to validate the authenticity of the verification flow by making an API call from your server to Truecaller's server.

```APIDOC
## GET /accessToken

### Description
Retrieves an access token for OTP verification. This token can be used by your server to validate the verification flow with Truecaller's servers.

### Method
GET

### Endpoint
/accessToken

### Parameters
None

### Request Example
(No request body for GET request)

### Response
#### Success Response (200)
- **accessToken** (string) - The access token for OTP verification.

#### Response Example
```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
```

--------------------------------

### Configure Info.plist for Truecaller SDK

Source: https://docs.truecaller.com/truecaller-sdk/ios/integrating-with-your-ios-app/configuration

Add the 'truesdk' entry to the LSApplicationQueriesSchemes array in your Info.plist file. This allows your application to query schemes related to the Truecaller SDK.

```xml
<key>LSApplicationQueriesSchemes</key>
<array>
<string>truesdk</string>
</array>
```

--------------------------------

### Verification Flow

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/non-truecaller-user-verification/completing-verification

This section details how to create a TrueProfile instance and initiate the verification process using either the missed call or IM OTP callback types.

```APIDOC
## Completing Verification

### Description
To complete the verification, create a `TrueProfile` instance by passing the user's first and last name. Then, based on the verification callback type, call either `verifyMissedCall` or `verifyOtp`.

### Method
POST (Implicit for verification initiation)

### Endpoint
`/verify` (Conceptual endpoint for verification process)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
**profile** (`TrueProfile` object) - Required - An instance of `TrueProfile` containing the user's first and last name.
**otp** (string) - Required (for IM OTP flow) - The One-Time Password received by the user.
**verificationCallback** (`VerificationCallback` object) - Required - The callback instance to handle verification results.

### Request Example
```java
// For Missed Call Verification
TrueProfile profile = new TrueProfile.Builder(firstName, lastName).build();
TcSdk.getInstance().verifyMissedCall(profile, verificationCallback);

// For IM OTP Verification
TrueProfile profile = new TrueProfile.Builder(firstName, lastName).build();
TcSdk.getInstance().verifyOtp(profile, otp, verificationCallback);
```

### Response
#### Success Response (200)
Indicates successful initiation or completion of the verification step. Specific success details depend on the `VerificationCallback` implementation.

#### Response Example
(Callback-based, no direct HTTP response body to display here)

### Notes
- The `firstName` and `lastName` for `TrueProfile` must contain at least one alphabet, be less than 128 characters, and `firstName` is mandatory while `lastName` can be empty but non-nullable.
- IM OTP flow requires Truecaller SDK 3.1.0 or later and may need to be enabled via early access by contacting developersupport@truecaller.com.
```

--------------------------------

### Get Authorization Code - Android

Source: https://docs.truecaller.com/truecaller-sdk/faqs/android-oauth-sdk

Retrieves the authorization code required for the OAuth flow. Ensure the correct activity or fragment instance is passed to the SDK.

```java
TcSdk.getInstance().getAuthorizationCode(this);
```

--------------------------------

### Set and Store OAuth State Parameter (Kotlin)

Source: https://docs.truecaller.com/truecaller-sdk/android/latest-oauth-sdk-3.2.1/integration-steps/setting-up-oauth-parameters

Generates a unique state parameter using BigInteger and SecureRandom, then stores it in the Truecaller SDK instance. This parameter is used to match the state received from the authorization server to prevent request forgery attacks.

```kotlin
stateRequested = BigInteger(130, SecureRandom()).toString(32)
TcSdk.getInstance().setOAuthState(stateRequested)
```

--------------------------------

### Implement TruecallerSDKDelegate Protocol in Swift

Source: https://docs.truecaller.com/truecaller-sdk/ios/integrating-with-your-ios-app/usage/swift

Designate your view controller as a TCTrueSDKDelegate to receive callbacks for Truecaller profile data or errors. This involves conforming to the protocol in your class definition.

```swift
class HostViewController: UIViewController, TCTrueSDKDelegate {
```
Tokens:
Raw