What happens if I import the same file twice?

Nothing duplicates. Imports upsert by external ID, so the second run updates the same contacts in place instead of creating new ones.

A column in my CSV didn't show up. Why?

Extra columns map to custom attributes by name. If you hadn't defined an attribute with that name, the value may not be stored as a typed field. Define the attribute and re-import.

Do contacts belong to the whole workspace or one agent?

One agent. Import to the agent that should own those contacts; importing to a different agent creates separate records there.

Is there a limit on how many contacts I can import at once?

Dashboard imports handle bulk files comfortably. For very large or repeated syncs, the Create contacts API accepts contacts in batches and is the recommended path.

Importing contacts

Bring contacts into Bookbag in bulk from CSV or JSON. Map core fields, route extra columns to custom attributes, and rely on external-ID upsert so re-running an import updates existing contacts instead of duplicating them.

View as Markdown

Already have your customers in a spreadsheet or another system? Import brings them into Bookbag in bulk. You can import from CSV or JSON, and Bookbag matches on the external ID so re-running an import safely updates existing contacts rather than creating duplicates.

Imports upsert by external ID

Every imported row needs an external ID. If a contact with that external ID already exists for the agent, the import updates it; if not, it creates a new one. This makes imports idempotent — run the same file twice and you get the same result, not duplicates.

Before you import

1
Decide your external ID
Pick the stable, unique-per-agent identifier you'll use as the match key — your own customer ID, user ID, or email. Make sure every row has one.
2
Define custom attributes you'll need
Create any custom attributes ahead of time so import columns map cleanly onto typed fields.
3
Prepare your file
Export a CSV or JSON with a column per field. Core fields map to name, email, and phone; everything else can map to custom attributes.

CSV imports

A CSV import expects a header row naming each column, then one contact per row. Columns that match core fields populate those fields; any extra columns are routed into custom attributes by name.

contacts.csv

external_id,name,email,phonenumber,plan_tier,lifetime_value,vip
cus_001,Jordan Lee,jordan@example.com,+15551234567,pro,842,true
cus_002,Sam Rivera,sam@example.com,+15559876543,free,0,false

Match column names to attribute names

Extra columns map to custom attributes by their machine name (e.g. plan_tier, not "Plan tier"). Name your CSV headers to match the attribute names and the mapping is automatic.

JSON imports

You can also import a JSON file — an array of contact objects with the same core fields and custom-attribute values. JSON is convenient when you're exporting straight from another system's API.

contacts.json

[
  {
    "external_id": "cus_001",
    "name": "Jordan Lee",
    "email": "jordan@example.com",
    "phonenumber": "+15551234567",
    "plan_tier": "pro",
    "lifetime_value": 842,
    "vip": true
  }
]

How fields are mapped

Column / key	Maps to
external_id	The contact's external ID (required — the match key for upsert).
name	Core name field.
email	Core email field.
phonenumber	Core phone field.
Any other column	A custom attribute, matched by attribute name. Define the attribute first so the value lands in a typed field.

Define attributes first for clean typing

If an extra column doesn't correspond to a defined custom attribute, its value can't be validated to a type. Create your custom attributes before importing so numbers, booleans, and dates are stored correctly.

Running the import

1
Open the import dialog
On the agent's Contacts tab, choose Import.
2
Upload your CSV or JSON
Select your prepared file.
3
Review and confirm
Bookbag parses the file and imports the contacts, upserting by external ID.
4
Verify in the table
Search and sort to confirm your contacts and attribute values landed as expected.

check

Because imports upsert, you can re-import a corrected file to fix mistakes — existing contacts are updated in place by their external ID.

Importing at scale via the API

For large or recurring syncs, use the API instead of a file. The Create contacts endpoint accepts a batch of contacts and upserts them by external ID — the same behavior as a dashboard import, driven from your own systems. This is the right approach for keeping Bookbag continuously in sync with your store or app.

Common questions

What's next

Custom attributes

Define the typed fields your import columns map onto.

Contacts overview

How contacts and external IDs work.

Create contacts API

Upsert contacts in bulk from your own systems.

List contacts API

Read contacts back out programmatically.

Custom attributes

Actions overview