> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contactsmanager.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with Contacts Manager in minutes

## Installation

ContactsManager offers two installation approaches. For production applications, we **strongly recommend** the [Full Installation](#2-full-installation-recommended) approach with server-side token generation.

### 1. Fast Installation (Client Only)

> [tab] Swift
>
> #### Swift Package Manager
>
> Add the ContactsManager package to your Swift project by adding it as a dependency in your `Package.swift` file:
>
> ```swift theme={null}
> dependencies: [
>     .package(url: "https://github.com/arpwal/contactsmanager-ios.git", from: "<latest-version>")
> ]
> ```
>
> #### SDK Initialization (Development Only)
>
> ```swift theme={null}
> import ContactsManager
>
> // Create user information
> let userInfo = UserInfo(
>     userId: "user123",
>     fullName: "John Doe",
>     email: "john@example.com",
>     phone: "+1234567890"
> )
>
> // Initialize with API key and user info (NOT RECOMMENDED for production)
> try await ContactsService.shared.initialize(
>     withAPIKey: "your-api-key",
>     token: nil, // Will generate token client-side with security warning
>     userInfo: userInfo,
>     options: ContactsManagerOptions(
>         verboseLogging: true,
>         autoSyncEnabled: true
>     )
> )
> ```

> [tab] React Native
>
> #### Installation
>
> ```bash theme={null}
> npm install @contactsmanager/rn
> # or
> yarn add @contactsmanager/rn
> ```
>
> #### SDK Initialization (Development Only)
>
> ```javascript theme={null}
> import { initialize, isInitialized } from '@contactsmanager/rn';
>
> // Create user information
> const userInfo = {
>   userId: "user123",
>   fullName: "John Doe",
>   email: "john@example.com",
>   phone: "+1234567890"
> };
>
> // Check if already initialized
> const alreadyInitialized = await isInitialized();
>
> // Initialize with API key and user info (NOT RECOMMENDED for production)
> const result = await initialize("your-api-key", userInfo, null, {
>   verboseLogging: true,
>   autoSyncEnabled: true
> });
> ```

> [tab] Objective-C
>
> #### SDK Initialization (Development Only)
>
> ```objc theme={null}
> #import <ContactsManager/ContactsManager.h>
>
> // Create user info
> CMUserInfo *userInfo = [[CMUserInfo alloc] init];
> userInfo.userId = @"user123";
> userInfo.email = @"user@example.com";
> userInfo.phone = @"+1234567890";
> userInfo.fullName = @"John Doe";
>
> // Initialize with options
> CMContactsManagerOptions *options = [CMContactsManagerOptions defaultOptions];
> options.verboseLogging = YES;
> options.autoSyncEnabled = YES;
>
> // Initialize the service (NOT RECOMMENDED for production)
> [[CMContactService sharedInstance] initializeWithAPIKey:@"your_api_key"
>                                                   token:nil // Will generate client-side
>                                                userInfo:userInfo
>                                                 options:options
>                                              completion:^(BOOL success, NSError * _Nullable error) {
>     if (success) {
>         NSLog(@"ContactsManager initialized successfully");
>     } else {
>         NSLog(@"Initialization failed: %@", error.localizedDescription);
>     }
> }];
> ```

> [tab] Kotlin
>
> #### SDK Initialization (Development Only)
>
> ```kotlin theme={null}
> // Initialize the library
> private val contactService by lazy { ContactService.getInstance(context) }
>
> // Create user info
> val userInfo = UserInfo(
>     userId = "user-123",
>     displayName = "John Doe",
>     email = "john@example.com",
>     phone = "+1234567890"
> )
>
> // Create options
> val options = CMContactsManagerOptions.defaultOptions().apply {
>     verboseLogging = true
>     autoSyncEnabled = true
> }
>
> // Initialize the service (NOT RECOMMENDED for production)
> val initResult = contactService.initialize(
>     apiKey = "your-api-key",
>     userInfo = userInfo,
>     options = options
> )
>
> if (initResult.isSuccess) {
>     // Service initialized successfully
>     val contacts = initResult.data
> } else {
>     // Handle initialization error
>     val error = initResult.error
> }
> ```

### 2. Full Installation (Recommended)

This is the secure, production-ready approach that sets up your server first to manage user creation and token generation.

#### Step A: Server Setup

Set up your backend to create users and generate authentication tokens for the ContactsManager SDK.

> [tab] Python
>
> #### Installation
>
> ```bash theme={null}
> pip install contactsmanager
> ```
>
> The Python SDK is open source and available on GitHub: [github.com/arpwal/contactsmanager-py](https://github.com/arpwal/contactsmanager-py)
>
> #### Create User (First Time Setup)
>
> ```python theme={null}
> from contactsmanager import ContactsManagerClient, UserInfo, DeviceInfo
>
> # Initialize the client
> client = ContactsManagerClient(
>     api_key="your-api-key",
>     api_secret="your-api-secret", 
>     org_id="your-org-id"
> )
>
> # Create user info
> user_info = UserInfo(
>     user_id="user-123",
>     full_name="John Doe",
>     email="john@example.com",  # Optional but recommended
>     phone="+1234567890",       # Optional but recommended
>     avatar_url="https://...",  # Optional
>     metadata={"key": "value"}  # Optional
> )
>
> # Create device info (optional)
> device_info = DeviceInfo(
>     device_name="iPhone 15",
>     os_version="iOS 17.5",
>     app_version="1.0.0"
> )
>
> # Create/update user and get token (first time or when user data changes)
> response = client.create_user(
>     user_info=user_info,
>     device_info=device_info,
>     expiry_seconds=86400  # 24 hours
> )
>
> # Use the token for client SDK initialization
> token = response.token
> user_data = response.user  # Created/updated user information
> ```
>
> #### Generate Token (Subsequent Logins)
>
> ```python theme={null}
> # For subsequent logins, generate a new token for existing users
> token_data = client.generate_token(
>     user_id="user-123",
>     device_info={"device_name": "iPhone 15", "os_version": "iOS 17.5"},
>     expiration_seconds=86400  # 24 hours
> )
>
> # The token to be used in client SDK initialization
> token = token_data["token"]
> ```

> [tab] Node.js
>
> #### Installation
>
> ```bash theme={null}
> npm install @contactsmanager/server
> ```
>
> The Node.js SDK is open source and available on GitHub: [github.com/arpwal/contactsmanager-nodejs](https://github.com/arpwal/contactsmanager-nodejs)
>
> Full documentation for the Node.js SDK is also available on [npm](https://www.npmjs.com/package/@contactsmanager/server).
>
> #### Create User (First Time Setup)
>
> ```javascript theme={null}
> import { ContactsManagerClient } from '@contactsmanager/server';
>
> // Initialize the client
> const client = new ContactsManagerClient({
>   apiKey: 'your-api-key',
>   apiSecret: 'your-api-secret',
>   orgId: 'your-org-id'
> });
>
> // Create/update user and get token (first time or when user data changes)
> async function createUserAndGetToken() {
>   const userInfo = {
>     userId: 'user-123',
>     fullName: 'John Doe',
>     email: 'john@example.com',      // Optional but recommended
>     phone: '+1234567890',           // Optional but recommended
>     avatarUrl: 'https://...',       // Optional
>     metadata: { key: 'value' }      // Optional
>   };
>
>   const deviceInfo = {
>     deviceName: 'iPhone 15',
>     osVersion: 'iOS 17.5',
>     appVersion: '1.0.0'
>   };
>
>   const response = await client.createUser(
>     userInfo,
>     deviceInfo,
>     86400  // 24 hours expiry
>   );
>
>   // Use the token for client SDK initialization
>   const token = response.token;
>   const userData = response.user;  // Created/updated user information
>
>   return { token, userData };
> }
> ```
>
> #### Generate Token (Subsequent Logins)
>
> ```javascript theme={null}
> // For subsequent logins, generate a new token for existing users
> async function generateUserToken() {
>   const tokenData = await client.generateToken({
>     userId: 'user-123',
>     deviceInfo: { deviceName: 'iPhone 15', osVersion: 'iOS 17.5' },
>     expirationSeconds: 86400 // 24 hours
>   });
>
>   // The token to be used in client SDK initialization
>   const token = tokenData.token;
>   return token;
> }
> ```

#### Step B: Client Setup

Install and initialize the ContactsManager SDK in your client application using the token from your server.

> [tab] Swift
>
> #### Swift Package Manager
>
> Add the ContactsManager package to your Swift project by adding it as a dependency in your `Package.swift` file:
>
> ```swift theme={null}
> dependencies: [
>     .package(url: "https://github.com/arpwal/contactsmanager-ios.git", from: "<latest-version>")
> ]
> ```
>
> Or in Xcode:
>
> 1. Go to File > Swift Packages > Add Package Dependency
> 2. Enter the repository URL: `https://github.com/arpwal/contactsmanager-ios.git`
> 3. Specify a minimum version of `<latest-version>` from the repository
> 4. Click Next and complete the integration
>
> #### SDK Initialization (Recommended)
>
> ```swift theme={null}
> import ContactsManager
>
> // Initialize the SDK with server-generated token (RECOMMENDED)
> try await ContactsService.shared.initialize(
>     withToken: "server-generated-token",
>     options: ContactsManagerOptions(
>         verboseLogging: false,
>         autoSyncEnabled: true
>     )
> )
> ```
>
> > [!NOTE]
> >
> > **This is the recommended approach**: The token should be generated by your server using the steps above. The SDK will automatically fetch user information from the server using the token, ensuring data consistency and security.

> [tab] React Native
>
> #### Installation
>
> ```bash theme={null}
> npm install @contactsmanager/rn
> # or
> yarn add @contactsmanager/rn
> ```
>
> #### Expo Setup
>
> If you're using Expo, you'll need to generate native dependencies before proceeding with platform setup:
>
> ```bash theme={null}
> npx expo prebuild
> ```
>
> This command will generate the iOS and Android native projects required for the ContactsManager SDK to work. After running prebuild:
>
> * The `ios` directory will be created/updated with CocoaPods setup
> * The `android` directory will be created/updated with Gradle setup
>
> Make sure to run prebuild again if you make changes to your native dependencies.
>
> #### Platform Setup
>
> ##### iOS Setup
>
> 1. Install CocoaPods dependencies:
>
> ```bash theme={null}
> cd ios && pod install && cd ..
> ```
>
> 2. Add permissions to `Info.plist`:
>
> ```xml theme={null}
> <key>NSContactsUsageDescription</key>
> <string>We need access to your contacts to enable social features</string>
> ```
>
> ##### Android Setup
>
> 1. Add the following permissions to your `android/app/src/main/AndroidManifest.xml`:
>
> ```xml theme={null}
> <!-- Required for accessing contacts -->
> <uses-permission android:name="android.permission.READ_CONTACTS" />
>
> <!-- Required for network operations -->
> <uses-permission android:name="android.permission.INTERNET" />
> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
> ```
>
> 2. Ensure your app's `minSdkVersion` in `android/build.gradle` is at least 21:
>
> ```gradle theme={null}
> buildscript {
>     ext {
>         minSdkVersion = 23
>     }
> }
> ```
>
> #### SDK Initialization (Recommended)
>
> ```javascript theme={null}
> import { initializeWithToken, isInitialized } from '@contactsmanager/rn';
>
> // Check if already initialized
> const alreadyInitialized = await isInitialized();
>
> // Initialize with server-generated token (RECOMMENDED)
> const result = await initializeWithToken("server-generated-token", {
>   verboseLogging: false,
>   autoSyncEnabled: true
> });
>
> // Basic Usage Example
> import { requestContactsAccess, hasContactsReadAccess, getContacts } from '@contactsmanager/rn';
>
> const requestAccess = async () => {
>   try {
>     const { granted } = await requestContactsAccess();
>     if (granted) {
>       const hasReadAccess = await hasContactsReadAccess();
>       if (hasReadAccess) {
>         const contacts = await getContacts();
>         console.log(`Retrieved ${contacts.length} contacts`);
>       }
>     }
>   } catch (error) {
>     console.error('Error accessing contacts:', error);
>   }
> };
> ```

> [tab] Objective-C
>
> #### Installation
>
> 1. Download the latest `ContactsManager.framework` from [Releases](https://github.com/arpwal/contactsmanager-objc/releases)
> 2. Drag and drop the framework into your Xcode project
> 3. Add framework to "Link Binary With Libraries" in Build Phases
> 4. Add to Info.plist:
>
> ```xml theme={null}
> <key>NSContactsUsageDescription</key>
> <string>We need access to contacts to enable social features.</string>
> ```
>
> #### SDK Initialization (Recommended)
>
> ```objc theme={null}
> #import <ContactsManager/ContactsManager.h>
>
> // Initialize with options (optional)
> CMContactsManagerOptions *options = [CMContactsManagerOptions defaultOptions];
> options.verboseLogging = NO;
> options.autoSyncEnabled = YES;
>
> // Initialize the service with server-generated token (RECOMMENDED)
> [[CMContactService sharedInstance] initializeWithToken:@"server-generated-token"
>                                                 options:options // Optional
>                                              completion:^(BOOL success, NSError * _Nullable error) {
>     if (success) {
>         NSLog(@"ContactsManager initialized successfully");
>     } else {
>         NSLog(@"Initialization failed: %@", error.localizedDescription);
>     }
> }];
> ```

> [tab] Kotlin
>
> #### Installation
>
> Add the library to your project's `build.gradle`:
>
> ```gradle theme={null}
> implementation("io.contactsmanager:contactsmanager:1.0.5")
> ```
>
> #### Get Latest Version
>
> You can check for the latest version of the SDK on [Maven Central](https://central.sonatype.com/artifact/io.contactsmanager/contactsmanager/overview).
>
> #### Required Permissions
>
> Add the following permissions to your `AndroidManifest.xml`:
>
> ```xml theme={null}
> <!-- Required for accessing contacts -->
> <uses-permission android:name="android.permission.READ_CONTACTS" />
>
> <!-- Required for network operations -->
> <uses-permission android:name="android.permission.INTERNET" />
> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
> ```
>
> #### SDK Initialization (Recommended)
>
> ```kotlin theme={null}
> // Initialize the library
> private val contactService by lazy { ContactService.getInstance(context) }
>
> // Create options
> val options = CMContactsManagerOptions.defaultOptions().apply {
>     verboseLogging = false
>     autoSyncEnabled = true
> }
>
> // Initialize the service with server-generated token (RECOMMENDED)
> val initResult = contactService.initializeWithToken(
>     token = "server-generated-token",
>     options = options
> )
>
> if (initResult.isSuccess) {
>     // Service initialized successfully
>     val userInfo = initResult.data
> } else {
>     // Handle initialization error
>     val error = initResult.error
> }
> ```

## Next Steps

> [card] [Accessing the API](https://docs.contactsmanager.io/services/accessing-api.md)
>
> Learn how to access and use the ContactsManager SDK API

> [card] [Contacts Authorization](https://docs.contactsmanager.io/services/contacts-authorization.md)
>
> Request and manage access to device contacts

> [card] [Search UI](https://docs.contactsmanager.io/services/search-ui)
>
> Build powerful contact search interfaces

> [card] [Recommendations](https://docs.contactsmanager.io/services/recommendations.md)
>
> Implement intelligent contact recommendations


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.