Managing Contacts at Scale

As your contact database grows, you need strategies for importing, organizing, and maintaining data quality. This guide covers techniques for working with thousands of contacts.

Importing contacts

Bulk upsert

The upsert endpoint is your primary tool for bulk imports:

curl -X POST https://api.gomobile.ma/api/contact/upsert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      { "primaryPhone": "[phone]", "firstName": "Ahmed", ... },
      { "primaryPhone": "[phone]", "firstName": "Fatima", ... }
    ]
  }'

Key behaviors:

• New contacts (phone not found) → Created

• Existing contacts (phone matches) → Updated

• Matching is by primaryPhone within your organization

Batch size

For large imports, batch your requests:

• Recommended batch size: 100-500 contacts per request

• Maximum: 1000 contacts per request (varies by plan)

• Rate limiting: 10 requests per second

Example batching logic:

const contacts = [...]; // Your full list
const batchSize = 500;

for (let i = 0; i < contacts.length; i += batchSize) {
  const batch = contacts.slice(i, i + batchSize);
  await fetch('/contact/upsert', {
    method: 'POST',
    body: JSON.stringify({ data: batch })
  });
  await sleep(100); // Small delay between batches
}

Preparing your data

Before importing:

1. Normalize phone numbers - Use E.164 format when possible

2. Remove duplicates - Same phone = same contact in Gomobile

3. Validate required fields - At minimum, primaryPhone

4. Map your fields - Match your data to Gomobile fields

5. Define custom attributes first - Create them before importing data that uses them

Field mapping

Map your source data to Gomobile fields:

Your field	Gomobile field
mobile	primaryPhone
name	fullName (or split into firstName/lastName)
mail	primaryEmail
balance	customAttributes.account_balance

Organizing with audiences

Audience strategies

By campaign type:

• Payment Reminders Q1

• New Customer Welcome

• Feedback Survey March

By customer segment:

• Premium Customers

• Standard Customers

• Trial Users

By geography:

• Casablanca Region

• Rabat Region

• Southern Morocco

By engagement level:

• Active (last 30 days)

• At Risk (60-90 days)

• Inactive (90+ days)

Dynamic segmentation

While Gomobile doesn't have automatic segmentation, you can simulate it:

1. Export contacts with specific criteria from your CRM

2. Create or update audience in Gomobile

3. Add matching contacts to the audience

4. Run campaigns against the audience

5. Repeat periodically to refresh

Audience refresh workflow

# 1. Create fresh audience
curl -X POST /audience -d '{"name": "High Balance Customers - Jan 2025"}'

# 2. Query your CRM for matching contacts
# (external to Gomobile)

# 3. Upsert contacts to Gomobile
curl -X POST /contact/upsert -d '{"data": [...]}'

# 4. Add to audience
curl -X POST /audience/{id}/add-contacts -d '{"contacts": [...]}'

Maintaining data quality

Regular cleanup tasks

Weekly:

• Remove bounced/invalid phone numbers

• Update changed contact information

• Merge duplicates

Monthly:

• Review contact engagement metrics

• Archive inactive contacts

• Validate custom attribute values

Handling duplicates

Duplicates usually happen when phone formats differ:

[phone]  ← E.164
0612345678     ← Local
212612345678   ← Without +

Prevention:

• Normalize phone formats before import

• Use consistent format throughout

Resolution:

• Export contacts with similar phones

• Decide which to keep

• Delete duplicates (soft delete preserves history)

• Update references if needed

Invalid phone numbers

Signs of invalid numbers:

• Calls immediately fail

• "Number not in service" errors

• Consistent "no answer" across all attempts

Handling:

• Flag contacts with repeated failures

• Review and remove invalid numbers

• Consider verification services for new data

Custom attributes at scale

Defining a schema

Plan your custom attributes before importing:

# Create attributes first
curl -X POST /custom-attributes -d '{"displayName": "Account Balance", "type": "number"}'
curl -X POST /custom-attributes -d '{"displayName": "Subscription Tier", "type": "text"}'
curl -X POST /custom-attributes -d '{"displayName": "Last Contact", "type": "date"}'

Bulk updating attributes

Use upsert to update attribute values in bulk:

curl -X POST /contact/upsert -d '{
  "data": [
    { "primaryPhone": "[phone]", "customAttributes": { "account_balance": 1500 } },
    { "primaryPhone": "[phone]", "customAttributes": { "account_balance": 2300 } }
  ]
}'

Only specified attributes are updated—others remain unchanged.

Syncing with external systems

CRM integration pattern

┌─────────────┐     Export      ┌─────────────┐
│    Your     │ ──────────────▶ │  Transform  │
│     CRM     │                 │   Script    │
└─────────────┘                 └──────┬──────┘
                                       │
                                       │ Upsert
                                       ▼
                               ┌─────────────┐
                               │  Gomobile   │
                               │     API     │
                               └─────────────┘

Sync frequency depends on your use case:

• Real-time: Webhook on CRM changes

• Hourly: Scheduled job for active campaigns

• Daily: Overnight batch for general sync

Handling deletes

When contacts are deleted in your source system:

1. Option A: Soft delete in Gomobile (preserves history)

2. Option B: Remove from active audiences (keeps contact but excludes from campaigns)

3. Option C: Flag with a custom attribute (e.g., is_active: false)

Search and filtering

Pagination best practices

Always paginate large result sets:

# First page
curl "/contact?page=1&limit=100"

# Subsequent pages
curl "/contact?page=2&limit=100"

Use the meta response to know when you're done:

{
  "meta": {
    "page": 2,
    "totalPages": 15,
    "hasNextPage": true
  }
}

Efficient searching

Use specific searches instead of loading all contacts:

# Search by name
curl "/contact?search=ahmed"

# Sorted by creation date
curl "/contact?sortBy=createdAt&sortOrder=desc"

Data export

For compliance or analysis, you might need to export data:

1. Paginate through all contacts

2. Collect into local storage

3. Transform as needed

4. Export to your format (CSV, Excel, etc.)

async function exportAllContacts() {
  let page = 1;
  let allContacts = [];

  while (true) {
    const response = await fetch(`/contact?page=${page}&limit=100`);
    const { data, meta } = await response.json();

    allContacts = allContacts.concat(data);

    if (!meta.hasNextPage) break;
    page++;
  }

  return allContacts;
}

Best practices summary

1. Use upsert for imports - Handles both create and update

2. Batch your requests - 100-500 contacts per request

3. Normalize phone numbers - Consistent format prevents duplicates

4. Define attributes first - Create before importing data

5. Segment with audiences - Don't try to filter at call time

6. Sync regularly - Keep Gomobile in sync with your source systems

7. Monitor data quality - Regular cleanup prevents issues

Next steps

• Audiences - Grouping contacts

• Custom Attributes - Extending contact data

• Building Your First Campaign - Using your contacts