iOS quickstart

Five minutes. Three edits to your project.

This page covers lookups inside your app. Naming callers on the incoming call screen is Live Caller ID, which is a much longer setup. See iOS Live Caller ID.

Before you start

Your app targets iOS 13.0 or later.

You use Xcode 16 or later.

You have your sdk_key and sdk_secret. See Get your keys.

Step 1: add the package

In Xcode, choose File > Add Package Dependencies.

Paste this URL into the search box at the top right:

https://github.com/dimondevceo/callerapi-sdk

Set Dependency Rule to Up to Next Major Version and leave 1.4.0. Click Add Package.

Xcode now asks which products to add. Tick CallerAPI only. Leave
CallerAPILiveCallerID unticked, because it needs iOS 18 and an app extension. Confirm the target is your app. Click Add Package.

Using CocoaPods instead

Add one line to your Podfile, then run pod install:

Using Package.swift instead

Step 2: add your credentials

You have two ways to do this. Pick one.

Option A: in code

Put this in application(_:didFinishLaunchingWithOptions:), or in the init of your App struct if you use SwiftUI:

Call it once, at launch, before your first lookup.

Option B: in Info.plist

Open Info.plist. Add two rows:

Key	Type	Value
`CallerAPISDKKey`	String	your SDK key
`CallerAPISDKSecret`	String	your SDK secret

With Option B you write no configuration code. The SDK reads the keys the first time you call a lookup.

Option A wins if you use both.

Step 3: look up a number

Both lookup functions are async and they can throw:

Run the app. The console prints Caller: CallerAPI LC.

That is the quickstart. Go to Check it works to confirm the dashboard sees your app.

Checking for spam

Handling errors properly

A thrown error is a CallerAPIError with a code. Code -2 means your credentials were refused, which is the failure you are most likely to hit first:

A nil result is not an error. It means the number does not belong to a business.

Errors lists every code.

Things that will confuse you

Every lookup throws code -2. The SDK has no credentials, or the server refused them. Confirm you called configure before the lookup, or that the two Info.plist keys are spelled exactly as above. Confirm your bundle identifier matches the app you created in the dashboard.

lookupLabel returns nil for every number. Try +18883578668, which is a known business. If that also returns nil, your credentials are not reaching the SDK.

Xcode cannot find CallerAPIConfig. You are missing import CallerAPI, or you added only the CallerAPILiveCallerID product. Both types live in CallerAPI.

Move your credentials out of source control

Create Secrets.xcconfig and add it to .gitignore:

CALLERAPI_SDK_KEY = paste-your-sdk-key
CALLERAPI_SDK_SECRET = paste-your-sdk-secret

In Project > Info > Configurations, set that file for Debug and Release. Then set the Info.plist values to $(CALLERAPI_SDK_KEY) and $(CALLERAPI_SDK_SECRET).

The SDK ignores a value that still looks like $(...), which happens when the configuration file is not wired up. That way a broken setup fails at your first lookup rather than sending a placeholder to the server.

Check it works

Name callers on the incoming call screen

All methods

iOS

iOS quickstart#

Before you start#

Step 1: add the package#

Using CocoaPods instead#

Using Package.swift instead#

Step 2: add your credentials#

Option A: in code#

Option B: in Info.plist#

Step 3: look up a number#

Checking for spam#

Handling errors properly#

Things that will confuse you#

Move your credentials out of source control#

Next#