Import rows from a script

Every change other than a payment goes through an import: you send rows, Campfire shows what it would do, and nothing is written until you apply. The app's spreadsheet import (Import & export in unit settings, then Choose a template) uses the same engine, so a script and a leader get the same results, and imports from both show in one history.

You need a token with imports:write (Import data in the app) and the permission the import type needs. The examples use the campfire.py helper from Getting started.

How an import works

POST /imports ──▶ previewed ──apply──▶ complete ──undo──▶ undone
                     │            └──▶ failed   ──undo──▶ undone
                     └── an hour passes, or the unit changed ──▶ expired

1. Preview. Send the rows. Campfire plans each one against the unit as it is now and saves the plan for an hour. Nothing in the unit changes.
2. Read the rows. Each row has an outcome: create, update, unchanged, skip, error or needs_choice. Updates list every field's old and new value.
3. Apply, with your choices for the rows that need one. Campfire plans the rows again. If the unit changed since the preview so the plan would differ, it refuses with 409 plan_changed and you preview again. What gets written is always what you saw.
4. Undo, if you need to, within 30 days. Every type can be undone except members.

Rules every import follows

• Blank cells never clear anything. A blank leaves the field as it is. Clear a value in the app.
• Imports never delete records. Only undo removes what that import added.
• Re-running the same rows is safe. Rows match the same records again and show as unchanged.
• Permissions are checked per row. A row you can't write is a skip with reason not_allowed; the rest still imports.
• Nobody is notified. No push, email or chat message comes from an import.
• Up to 5,000 rows and, for a file, 10 MB.

Import types

GET /import-types lists the types. GET /import-types/{type} lists each column's key, spreadsheet header, whether it is required, its format, allowed values where there is a fixed list, and inTemplate. GET /import-types/{type}/template.csv is the empty spreadsheet: just the header row, with the columns whose inTemplate is true. Ids Campfire fills into its own files have inTemplate: false: memberId in every type, and eventId and eventExternalId in attendance. An import still accepts them. These three need a token but no particular scope.

GET /me lists the types you can import right now under capabilities.importTypes.

Dates

Date cells accept 2019-06-14 or 6/14/2019, and in an Excel file, a date cell. Event times have their own formats; see events.

Naming the member (every type but members and events)

A member reference is one of these, tried in order:

1. memberId: the Campfire id, from the roster read or the app's roster download. Blank templates leave it out.
2. bsaMemberId: the BSA member ID on the member's profile, when exactly one member has it.
3. firstName and lastName (the first name can also be the nickname), narrowed by memberType (youth or adult) when you give it. Former members match too; their history is still theirs.

No match is needs_choice with reason not_found. Several matches are needs_choice with reason ambiguous and the candidates.

activities

Written as manual entries with no event attached, the way the TroopTrack import writes them. Don't import activities for events that already award credits in Campfire, or they count twice.

healthForms

Give at least one of the two dates. A member has one health form, so there is no externalId: each row updates that member's form, and a member on two rows is an error. An uploaded form file stays on the record.

members

Matching for members: memberId, then an externalId from an earlier import, then bsaMemberId (exactly one member), then exactly one member with that name and type. Several name matches are needs_choice, settled with "new" or "skip" (see Apply). No match creates a new member, so look over every create row: a nickname mismatch would otherwise add a duplicate. The same new person twice in one file (same name and type, or same externalId), or the same existing member twice, is an error on the later row.

• Adding people needs directory:add_members (or directory:edit_members). Changing anyone who already exists, and linking households, needs directory:edit_members. The roles column needs organization:manage_roles.
• New members get default_member plus any roles in the row. Each added role gets a role history entry starting today, as Assign Roles in the app does.
• Households link through the same code as linking a parent and Scout in the app. When two existing families would join, the preview carries a merges_families warning.
• A leftDate for someone who uses the app is a skip with reason has_account. Remove them in the app, one person at a time, so their access ends on purpose.
• In an update, changes shows old contact values only for members whose details you can see in the app; others show null.
• Member imports can't be undone. Adding people ripples into chats, families and roles. Check the preview; fix a wrong value with a corrected import.

roleHistory

Needs organization:manage_roles. Adds past positions to the member's role history, as Previous Roles in the app does. It never changes anyone's current roles: those go in the roles column of a members import. A position with the same role and dates already added in the app shows as unchanged rather than being added twice. Undo keeps an entry edited in the app since.

events

• Times. 2026-11-13 18:00, 11/13/2026 6:00 PM, either with seconds (11/13/2026 18:00:00, as Google Sheets exports them), or ISO 8601 with an offset such as 2026-11-13T18:00-05:00, +0500 or Z. A time with no offset is read in the unit's time zone, or Eastern time if the unit has none set. A date alone in both startAt and endAt makes an all-day event, from midnight on the first day to 11:59 PM on the last, as the app saves one. There is no separate all-day column.
• The type is available with events:create or events:edit. Creating an event needs events:create; updating one needs events:edit. Undoing an events import needs events:delete, as deleting an event in the app does.
• An import only updates events an earlier import created. It never changes events made in the app.
• Imported events have no cost and ask for RSVPs. An import never cancels or deletes an event, and creating one notifies nobody.

attendance

• Needs events:sign_up_others. On an event that doesn't take RSVPs, a row also needs events:edit.
• In Campfire, attendance is the RSVP. Each row creates or updates that person's RSVP, and the event's credits follow, as when a leader marks attendance in the app. Don't also import activities for the same events, or the credits count twice.
• Name each event by eventId, by eventExternalId, or by eventTitle and eventDate, the way a leader knows it. By title and date, no event with that title starting that day is unknown_event, and two or more is ambiguous_event: rename one in Campfire, then preview again.
• The event must have ended and must not be canceled. Otherwise the row is an error with reason not_ended or canceled; an event Campfire can't find is unknown_event.
• An event with a cost bills attendees, as the app's Attendance report does. Imported events never have a cost, so history never bills anyone. On an event that does, the preview carries a charges_families warning with the number of families and the total in amountCents. Changing someone to not_attending on such an event removes their charge, as in the app, and the preview carries a removes_charges warning the same way. Read them before you apply. If the event's cost changes after the preview, apply answers 409 plan_changed; preview again.

advancement

• Each item type needs its sign-off permission: ranks and adventures advancement:approve_rank, merit badges advancement:approve_merit_badges, awards advancement:manage_awards. Other rows are skipped with not_allowed.
• Rows for the same Scout and item make one record. There is no externalId.
• Blanks only. A date Campfire already has is never changed. The row says so in its message.
• Undo needs the sign-off permission for each item type it removes. Removing a completed rank recalculates the Scout's permissions, so sign-off rights the rank gave go with it.
• Nothing is earned on its own. An import writes exactly the dates in its rows. Completing every requirement doesn't date the item, and the preview doesn't point that out: give the item its own row. Linked rank requirements and elective slots are filled only when a leader signs off in the app.

accountHistory

• Needs finances:manage, and Campfire Pro or a trial with finances turned on (403 feature_disabled otherwise).
• Never payments. Rows become charges and credits, so old deposits don't count as cash on hand. To bring in a starting balance, one row per family dated at your cutover is enough.
• Closed months. A row dated in a closed month is an error, and so is a change to an existing entry in one. Undo is refused with 409 month_closed if any entry it would remove is in a month closed since.
• Family balances are recalculated after the import, and again after undo. One import or undo runs at a time in a unit, so two can't set a balance at once.

Preview

POST /organizations/{orgId}/imports takes rows as JSON or as a file.

JSON rows

POST /api/v1/organizations/{orgId}/imports
Content-Type: application/json

{
  "type": "activities",
  "rows": [
    { "externalId": "tm-48213", "firstName": "Sam", "lastName": "Lee", "memberType": "youth",
      "type": "camping", "amount": 2, "date": "2019-06-14", "description": "Summer camp" },
    { "externalId": "tm-48214", "bsaMemberId": "136680564",
      "type": "service", "amount": 3, "date": "7/2/2019" }
  ]
}

• Use the column keys. An unknown key refuses the whole request.
• Values may be text, numbers or true/false. Empty strings and null are treated as blank.
• Row numbers in the results are 1-based positions in your rows list.

A CSV or Excel file

Send the file as the body with Content-Type: text/csv or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, and the type in the query string: ?type=members.

• The header row may use the keys (firstName) or the template headers ("First name"). It must be in the first 10 lines.
• Columns Campfire doesn't know are ignored and listed in a ignored_columns warning.
• Row numbers in the results are the spreadsheet's line numbers, so the first row under the header is row 2.
• If Excel turned long ids into values like 1.36681E+08, the file is refused. Format those columns as Text, or start from a fresh download.

# The empty template, with the column headers Campfire expects
curl -sS -o health-forms.csv \
  -H "Authorization: Bearer $CAMPFIRE_API_TOKEN" \
  https://troopcampfire.app/api/v1/import-types/healthForms/template.csv

# Fill it in, then preview it
curl -sS -X POST "https://troopcampfire.app/api/v1/organizations/$ORG_ID/imports?type=healthForms" \
  -H "Authorization: Bearer $CAMPFIRE_API_TOKEN" \
  -H "Content-Type: text/csv" \
  --data-binary @health-forms.csv

The response

201 with the import. Its id starts with imp_.

{
  "data": {
    "id": "imp_2kx9q81b04f7c2a9",
    "type": "activities",
    "source": "api",
    "status": "previewed",
    "createdAt": "2026-11-02T14:04:05.000Z",
    "createdByName": "Pat Kim",
    "expiresAt": "2026-11-02T15:04:05.000Z",
    "summary": { "rows": 412, "create": 380, "update": 0, "unchanged": 20,
                 "skip": 8, "error": 2, "needsChoice": 2 },
    "warnings": [],
    "appliedAt": null,
    "finishedAt": null,
    "undoUntil": null,
    "undoneAt": null,
    "undoResult": null,
    "error": null
  },
  "requestId": "..."
}

warnings carries what you must see before applying: ignored_columns (with columns), merges_families (with count), and for attendance charges_families and removes_charges (with count and amountCents).

Read the rows

GET /organizations/{orgId}/imports/{importId}/rows is a paginated list in row order. Add ?outcome=needs_choice (or any other outcome) to see only those. Rows hold the cells you uploaded, so only the person who ran the import can read them (anyone else gets 404), and they are deleted 31 days after the preview or apply. name is the first and last name as the row gives them.

{ "row": 2, "outcome": "create", "recordId": "imp_5d1e..." }
{ "row": 13, "name": "Alex Kim", "outcome": "needs_choice", "reason": "ambiguous",
  "candidates": [
    { "memberId": "a1...", "firstName": "Alex", "lastName": "Kim", "isAdult": false },
    { "memberId": "b2...", "firstName": "Alex", "lastName": "Kim", "isAdult": true } ] }
{ "row": 14, "name": "Sam Lee", "outcome": "update", "recordId": "imp_9c0a...",
  "changes": { "amount": { "from": 2, "to": 3 } } }
{ "row": 15, "name": "Jo Park", "outcome": "error", "reason": "invalid_value", "column": "date",
  "message": "Date must look like 2019-06-14 or 6/14/2019." }

Every error row, and a skip for not_allowed or has_account, has a message you can show to a person, and so does an ambiguous members row. needs_choice rows have reason and candidates. After apply, each row holds its final outcome. After undo, "undo": "kept" marks an added record that was left in place.

Apply

POST /organizations/{orgId}/imports/{importId}/apply with your choices:

{ "choices": { "13": "a1...", "22": "skip" } }

• Keys are row numbers, as strings. Only rows waiting for a choice may appear; anything else refuses the request.
• For every type that names a member (all but members and events), a value is a member id (one of the candidates, or any member of the unit for a not_found row), or "skip" to leave the row out.
• For members, a value is only "new" (add the row as a new person) or "skip". A member id is refused with 400: it would write changes nobody saw in the preview. To update one of the people the name matched, put their Campfire ID in the row's memberId and preview again. The row's message says so too.
• Rows still waiting with no choice are skipped. Send {} when there is nothing to choose.

Apply runs inside the request. When it finishes within about a minute it answers 200 with the finished import, status: "complete", a final summary, and undoUntil for types that can be undone. Calling apply again doesn't apply twice; it returns the import as it stands. Only the person who made the preview can apply it; anyone else gets a 403. A retry may send the same choices again.

Undo

POST /organizations/{orgId}/imports/{importId}/undo with an empty body answers 200 with status: "undone" and undoResult: how many records were removed and kept.

undone = call("POST", f"{base}/{imp}/undo", body={})["data"]
print(undone["status"], undone["undoResult"])   # undone {'removed': 380, 'kept': 0}

• Undo removes the records the import added, unless someone has changed or used them in the app since: a corrected amount, a health form uploaded again or given notes, an advancement record with a new date, sign-off or note, an RSVP changed, or an event that was edited, canceled, or has RSVPs, rides, a checklist, an event chat or files. Those are kept and counted in kept. Undo an attendance import before the events import it used.
• Undoing attendance removes the charges its RSVPs caused and the camping nights and service hours they earned. Manual activity entries stay. Undoing account history recalculates the families' balances.
• Changes the import made to records that already existed stay. Fix a wrong value with a corrected import.
• Only a complete or failed import from the last 30 days can be undone (undoUntil, counted from when apply started). Anything else, and every members import, is 409 not_undoable.
• Undo needs a permission the import type needs, but not the feature: you can undo a health form import after health forms were turned off. It also needs the permission to delete each record it removes (events:delete for events, the sign-off permission for advancement); otherwise it is 403 access_denied and nothing is removed. Undoing an import that is already undone returns it unchanged.
• A long undo can end in a 504 like a long apply (see above). It carries on; poll the import until status is undone.

History

GET /organizations/{orgId}/imports lists imports newest first, from the app (source: "app") and the API ("api"). Like the app's import history, it shows every import in the unit to anyone whose role includes some kind of import; anyone else gets a 403. GET /organizations/{orgId}/imports/{importId} reads one. status is previewed, expired, running, complete, failed or undone.

Limits

• Previews: 20 an hour per account.
• Applies and undos together: 10 an hour per unit, and one running at a time.
• 5,000 rows and 10 MB per import. A preview lasts an hour.

A whole script

Preview activity rows, show the problems, ask a person to settle each open row, then apply.

"""Bring in activity history: preview, settle the open rows, apply."""
from urllib.parse import quote
from campfire import call, CampfireError
import time

org = quote(call("GET", "/me")["data"]["organizationId"], safe="")
base = f"/organizations/{org}/imports"

rows = [
    {"externalId": "tm-48213", "firstName": "Sam", "lastName": "Lee", "memberType": "youth",
     "type": "camping", "amount": 2, "date": "2019-06-14", "description": "Summer camp"},
    {"externalId": "tm-48214", "bsaMemberId": "136680564",
     "type": "service", "amount": 3, "date": "2019-07-02"},
]

preview = call("POST", base, body={"type": "activities", "rows": rows})["data"]
imp = quote(preview["id"], safe="")
print("Preview:", preview["summary"], preview["warnings"])


def rows_with(outcome):
    query = {"outcome": outcome, "limit": 50}
    while True:
        page = call("GET", f"{base}/{imp}/rows", query=query)
        yield from page["data"]
        if page["nextCursor"] is None:
            return
        query["cursor"] = page["nextCursor"]


for row in rows_with("error"):
    print(f"Row {row['row']}: {row.get('column', '')} {row['message']}")

choices = {}
for row in rows_with("needs_choice"):
    candidates = row.get("candidates", [])
    print(f"Row {row['row']} ({row['reason']}):")
    for number, person in enumerate(candidates, 1):
        kind = "adult" if person["isAdult"] else "youth"
        print(f"  {number}. {person['firstName']} {person['lastName']} ({kind})")
    pick = input("  Number to use, or Enter to leave the row out: ").strip()
    choices[str(row["row"])] = candidates[int(pick) - 1]["memberId"] if pick else "skip"

def wait_until_finished():
    """Poll the import after a 504 or timeout: the apply is still running."""
    while True:
        time.sleep(5)
        current = call("GET", f"{base}/{imp}")["data"]
        if current["status"] not in ("previewed", "running"):
            return current

if input("Apply? [y/N] ").strip().lower() == "y":
    try:
        done = call("POST", f"{base}/{imp}/apply", body={"choices": choices})["data"]
    except (CampfireError, OSError) as error:
        if isinstance(error, CampfireError) and error.status != 504:
            raise
        done = wait_until_finished()
    print(done["status"], done["summary"], done["error"] or "")
    print("Undo possible until", done["undoUntil"])

Example: past events and who went

Bring in last year's outings from another system, then who attended each one. The events import comes first, because attendance names each event by the externalId it was imported with, or by its title and start date. Each import is previewed, checked and applied on its own.

"""Import past events, then attendance on them."""
from urllib.parse import quote
from campfire import call

org = quote(call("GET", "/me")["data"]["organizationId"], safe="")
base = f"/organizations/{org}/imports"


def preview_and_apply(import_type, rows):
    preview = call("POST", base, body={"type": import_type, "rows": rows})["data"]
    imp = quote(preview["id"], safe="")
    print(import_type, preview["summary"])
    for warning in preview["warnings"]:
        print("  Warning:", warning)
    problems = call("GET", f"{base}/{imp}/rows", query={"outcome": "error", "limit": 50})["data"]  # first 50
    for row in problems:
        print(f"  Row {row['row']}: {row.get('column', '')} {row['message']}")
    if input(f"Apply the {import_type} import? [y/N] ").strip().lower() != "y":
        raise SystemExit("Stopped before applying.")
    return call("POST", f"{base}/{imp}/apply", body={"choices": {}})["data"]


preview_and_apply("events", [
    {"externalId": "tm-ev-2025-10", "title": "October Campout", "eventType": "Campout",
     "startAt": "2025-10-17 18:00", "endAt": "2025-10-19 11:00",
     "location": "Camp Sequassen", "campingNights": 2},
    {"externalId": "tm-ev-2025-11", "title": "Food drive", "eventType": "Community Service",
     "startAt": "2025-11-08", "endAt": "2025-11-08", "serviceHours": 3},   # all day
])

preview_and_apply("attendance", [
    {"eventExternalId": "tm-ev-2025-10", "firstName": "Sam", "lastName": "Lee",
     "memberType": "youth", "status": "attending"},
    {"eventExternalId": "tm-ev-2025-10", "bsaMemberId": "136680564", "status": "attending"},
    # The way a leader names it: title and the day it started
    {"eventTitle": "Food drive", "eventDate": "2025-11-08", "firstName": "Sam",
     "lastName": "Lee", "memberType": "youth", "status": "not_attending"},
])

• The times have no offset, so they are read in your unit's time zone. The food drive has a date alone at both ends, so it is an all-day event.
• Sam and the second Scout get the October campout's two camping nights from the event's credits, as if a leader had marked them attending. Don't also import those nights as activities.
• The last row names the food drive by title and date, as a spreadsheet from the template does. That works for any event in Campfire, including ones made in the app, as long as no other event with that title started the same day.
• These events have no cost, so no family is billed. Attendance on an existing event with a cost would show a charges_families or removes_charges warning before you apply.
• This example leaves out rows that need a choice (they are skipped) and the 504 handling from the script above. Add both for a big import.