nlpearl

NLPearl Python Wrapper

NLPearl is a Python wrapper for the NLPearl API, allowing developers to interact seamlessly with NLPearl's services. This package supports both API V1 and V2 with a unified interface.

Table of Contents

• Installation
• Getting Started
• Quick Start
• API Versions
• Usage Guide
  • V2 API (Default)
  • V1 API
  • Shared Methods
• Complete API Reference
• Migration Guide
• License

Installation

pip install nlpearl

Getting Started

• Get your API key from NLPearl
• Set your API version (V2 is default)
• Start making API calls!

import nlpearl as pearl

# Configuration
pearl.api_key = "your_api_key_here"
pearl.api_version = "v2"  # Default, can be "v1" or "v2"

Quick Start

V2 Example (Default)

import nlpearl as pearl

pearl.api_key = "your_key"
pearl.api_version = "v2"  # Default

# Get all pearls
pearls = pearl.Pearl.get_all()

# Add a lead using pearl_id
pearl.Outbound.add_lead(
    pearl_id,
    phone_number="[phone]",
    call_data={"firstName": "John"}
)

# Get analytics
analytics = pearl.Pearl.get_analytics(
    pearl_id,
    from_date="2024-01-01T00:00:00.000Z",
    to_date="2024-01-31T23:59:59.999Z"
)

V1 Example

import nlpearl as pearl

pearl.api_key = "your_key"
pearl.api_version = "v1"

# Get all inbounds
inbounds = pearl.Inbound.get_all()

# Add a lead using outbound_id
pearl.Outbound.add_lead(
    outbound_id,
    phone_number="[phone]",
    call_data={"firstName": "John"}
)

# Get analytics
analytics = pearl.Outbound.get_analytics(
    outbound_id,
    from_date="2024-01-01T00:00:00.000Z",
    to_date="2024-01-31T23:59:59.999Z"
)

API Versions

The wrapper uses the same class names for both V1 and V2, automatically routing to the correct endpoints based on pearl.api_version.

Version Differences

Feature	V1	V2
Default	No	Yes
Structure	Separate Inbound/Outbound	Unified Pearl
ID Parameter	outbound_id, inbound_id	pearl_id
Classes	Inbound, Outbound	Pearl
Lead Operations	Outbound.add_lead(outbound_id, ...)	Outbound.add_lead(pearl_id, ...)

Unified API Approach

✅ Same class names - Use pearl.Outbound, pearl.Pearl, pearl.Inbound
✅ Automatic routing - Methods route to correct version based on api_version
✅ Clear errors - Helpful messages when using wrong version
✅ Version switching - Change api_version anytime

No separate V2 classes needed! Just set the version once and use the same API.

Usage Guide

V2 API (Default)

Pearl Management

pearl.api_version = "v2"

# Get all pearls
pearls = pearl.Pearl.get_all()

# Get specific pearl
pearl_details = pearl.Pearl.get(pearl_id)

# Activate/Deactivate
pearl.Pearl.set_active(pearl_id, is_active=True)

# Get ongoing calls
ongoing = pearl.Pearl.get_ongoing_calls(pearl_id)

# Get calls with filters
calls = pearl.Pearl.get_calls(
    pearl_id,
    from_date=datetime(2024, 1, 1),
    to_date=datetime(2024, 1, 31),
    tags=["important"],
    statuses=[100, 130]
)

# Get analytics
analytics = pearl.Pearl.get_analytics(pearl_id, from_date, to_date)

Lead Management (V2)

# Add lead (using pearl_id)
lead = pearl.Outbound.add_lead(
    pearl_id,
    phone_number="[phone]",
    external_id="ext123",
    time_zone_id="Pacific Standard Time",
    call_data={"firstName": "John", "lastName": "Doe"}
)

# Get lead
lead = pearl.Outbound.get_lead_by_id(pearl_id, lead_id)
lead = pearl.Outbound.get_lead_by_external_id(pearl_id, "ext123")
lead = pearl.Outbound.get_lead_by_phone_number(pearl_id, "[phone]")

# Update lead
pearl.Outbound.update_lead(
    pearl_id,
    lead_id,
    status=100,  # Mark as Success
    call_data={"notes": "Contact successful"}
)

# Search leads
leads = pearl.Outbound.get_leads(
    pearl_id,
    statuses=[1, 10],  # New and NeedRetry
    search_input="John",
    limit=50
)

# Delete leads
pearl.Outbound.delete_leads(pearl_id, [lead_id1, lead_id2])
pearl.Outbound.delete_leads_by_external_id(pearl_id, ["ext1", "ext2"])

V1 API

Inbound Operations (V1 Only)

pearl.api_version = "v1"

# Get all inbounds
inbounds = pearl.Inbound.get_all()

# Get specific inbound
inbound = pearl.Inbound.get(inbound_id)

# Activate/Deactivate
pearl.Inbound.set_active(inbound_id, is_active=True)

# Get ongoing calls
ongoing = pearl.Inbound.get_ongoing_calls(inbound_id)

# Get calls
calls = pearl.Inbound.get_calls(
    inbound_id,
    from_date=datetime(2024, 1, 1),
    to_date=datetime(2024, 1, 31),
    tags=["important"]
)

# Get analytics
analytics = pearl.Inbound.get_analytics(inbound_id, from_date, to_date)

Outbound Operations (V1)

# Get all outbounds
outbounds = pearl.Outbound.get_all()

# Get specific outbound
outbound = pearl.Outbound.get(outbound_id)

# Activate/Deactivate
pearl.Outbound.set_active(outbound_id, is_active=True)

# Get calls
calls = pearl.Outbound.get_calls(
    outbound_id,
    from_date=datetime(2024, 1, 1),
    to_date=datetime(2024, 1, 31)
)

# Make a call
result = pearl.Outbound.make_call(
    outbound_id,
    to="[phone]",
    call_data={"firstName": "Jane"}
)

# Get call requests
requests = pearl.Outbound.get_call_requests(
    outbound_id,
    from_date=datetime(2024, 1, 1),
    to_date=datetime(2024, 1, 31)
)

# Get analytics
analytics = pearl.Outbound.get_analytics(outbound_id, from_date, to_date)

Lead Management (V1)

# Add lead (using outbound_id)
lead = pearl.Outbound.add_lead(
    outbound_id,  # Note: outbound_id in V1, pearl_id in V2
    phone_number="[phone]",
    external_id="ext123",
    call_data={"firstName": "John"}
)

# Update lead
pearl.Outbound.update_lead(outbound_id, lead_id, status=100)

# Search leads
leads = pearl.Outbound.get_leads(
    outbound_id,
    status=1  # Note: V1 uses 'status', V2 uses 'statuses'
)

# Other lead methods work the same
lead = pearl.Outbound.get_lead_by_id(outbound_id, lead_id)
pearl.Outbound.delete_leads(outbound_id, [lead_id1, lead_id2])

Shared Methods

These methods work in both V1 and V2:

Account

# Works in both versions
account = pearl.Account.get_account()
print(f"Balance: {account['creditBalance']}")

Call Operations

# Get call info (both versions)
call = pearl.Call.get_call(call_id)

# Delete calls (both versions)
pearl.Call.delete_calls([call_id1, call_id2])

Memory Management

# V1
pearl.Pearl.reset_customer_memory(pearl_id, phone_number)

# V2 (same method works)
pearl.Pearl.reset_memory(pearl_id, phone_number)

Complete API Reference

Method Availability

Class	Method	V1	V2	Notes
Account	get_account()	✅	✅
Call	get_call(call_id)	✅	✅
Call	delete_calls(call_ids)	✅	✅
Inbound	get_all()	✅	❌	Use Pearl.get_all() in V2
Inbound	get(inbound_id)	✅	❌	Use Pearl.get(pearl_id) in V2
Inbound	set_active(...)	✅	❌	Use Pearl.set_active(...) in V2
Inbound	get_calls(...)	✅	❌	Use Pearl.get_calls(...) in V2
Inbound	get_ongoing_calls(...)	✅	❌	Use Pearl.get_ongoing_calls(...) in V2
Inbound	get_analytics(...)	✅	❌	Use Pearl.get_analytics(...) in V2
Outbound	get_all()	✅	❌	Use Pearl.get_all() in V2
Outbound	get(outbound_id)	✅	❌	Use Pearl.get(pearl_id) in V2
Outbound	set_active(...)	✅	❌	Use Pearl.set_active(...) in V2
Outbound	get_calls(...)	✅	❌	Use Pearl.get_calls(...) in V2
Outbound	add_lead(id, ...)	✅	✅	V1: outbound_id, V2: pearl_id
Outbound	update_lead(id, ...)	✅	✅	V1: outbound_id, V2: pearl_id
Outbound	get_leads(id, ...)	✅	✅	V1: outbound_id, V2: pearl_id
Outbound	get_lead_by_id(id, ...)	✅	✅	V1: outbound_id, V2: pearl_id
Outbound	get_lead_by_external_id(id, ...)	✅	✅	V1: outbound_id, V2: pearl_id
Outbound	get_lead_by_phone_number(id, ...)	✅	✅	V1: outbound_id, V2: pearl_id
Outbound	delete_leads(id, ...)	✅	✅	V1: outbound_id, V2: pearl_id
Outbound	delete_leads_by_external_id(id, ...)	✅	✅	V1: outbound_id, V2: pearl_id
Outbound	make_call(...)	✅	❌	V1 only
Outbound	get_call_request(...)	✅	❌	V1 only
Outbound	get_call_requests(...)	✅	❌	V1 only
Outbound	get_analytics(...)	✅	❌	Use Pearl.get_analytics(...) in V2
Pearl	reset_customer_memory(...)	✅	✅
Pearl	reset_memory(...)	✅	✅	Same as above
Pearl	get_all()	❌	✅	V2 only
Pearl	get(pearl_id)	❌	✅	V2 only
Pearl	set_active(...)	❌	✅	V2 only
Pearl	get_calls(...)	❌	✅	V2 only
Pearl	get_ongoing_calls(...)	❌	✅	V2 only
Pearl	get_analytics(...)	❌	✅	V2 only

Status Codes

Lead Status

• 1 - New
• 10 - NeedRetry
• 100 - Success
• 110 - NotSuccessful
• 130 - Completed
• 150 - Unreachable
• 220 - Blacklisted
• 500 - Error

Call Status

• 3 - InProgress
• 4 - Completed
• 5 - Busy
• 6 - Failed
• 7 - NoAnswer
• 8 - Canceled

Activity Status

• 1 - Running
• 2 - Paused
• 3 - Suspended
• 10 - TemporaryMaintenance

Migration Guide

From V1 to V2

Before (V1):

pearl.api_version = "v1"

# Get outbounds
outbounds = pearl.Outbound.get_all()

# Add lead
pearl.Outbound.add_lead(outbound_id, phone_number="+123...")

# Get analytics
analytics = pearl.Outbound.get_analytics(outbound_id, from_date, to_date)

After (V2):

pearl.api_version = "v2"

# Get pearls (replaces outbounds/inbounds)
pearls = pearl.Pearl.get_all()

# Add lead (same method, different ID)
pearl.Outbound.add_lead(pearl_id, phone_number="+123...")

# Get analytics (use Pearl class)
analytics = pearl.Pearl.get_analytics(pearl_id, from_date, to_date)

Key Changes

• Replace outbound_id/inbound_id with pearl_id
• Use Pearl class for analytics, calls, and pearl management
• Keep using Outbound for lead operations (just change the ID)
• Inbound class is V1-only, use Pearl in V2

Error Handling

The wrapper provides clear error messages when using methods in the wrong version:

pearl.api_version = "v2"
pearl.Inbound.get_all()
# ValueError: Inbound.get_all() is only available in API v1.
# In v2, use Pearl.get_all() instead.

License

BSD 3-Clause License - see LICENSE file for details.

Contact

• Support: [e-mail]
• Documentation: This README
• API Key: Contact [e-mail]

Version: 2.0.0 Python: 3.6+
API Versions: V1 and V2 supported