# Bulk import

A CSV to passes. Runs in your test sandbox: nothing is issued, every pass is a test preview. Authenticate with `Authorization: Bearer $PASSBOOK_KEY`. Ids in the examples are placeholders: use the ids your sandbox returns.

Turn a spreadsheet into passes in three calls: create the import, check it, commit it. Check reports every row that would fail before anything is made. A sandbox makes test previews only.

## Create the import

The file is sent as text. Map its columns in the next step.

```json
{
  "templateId": "0193a1b2-7c00-7000-8000-0000000000b1",
  "source": {
    "kind": "file",
    "name": "guests.csv",
    "csv": "attendee,ticket,email\nAda Example,TICKET-1001,ada@example.com\nGrace Host,TICKET-1002,grace@example.com\nAlan Guest,TICKET-1003,alan@example.com\nEdsger Visitor,TICKET-1004,edsger@example.com\nBarbara Member,TICKET-1005,barbara@example.com"
  }
}
```

Keep the import `id`.

## Check the rows

Map each template field to a column or a constant. Paste the import `id` into the path.

```json
{
  "plan": {
    "mapping": {
      "attendee": { "from": "attendee" },
      "ticketId": { "from": "ticket" },
      "eventName": { "from": "attendee", "transform": { "kind": "constant", "options": { "value": "Harbor Night" } } },
      "venueName": { "from": "attendee", "transform": { "kind": "constant", "options": { "value": "Harbor Hall" } } },
      "venueRegion": { "from": "attendee", "transform": { "kind": "constant", "options": { "value": "Cupertino, CA" } } },
      "startsAt": { "from": "attendee", "transform": { "kind": "constant", "options": { "value": "2030-06-01T19:00:00-07:00" } } },
      "endsAt": { "from": "attendee", "transform": { "kind": "constant", "options": { "value": "2030-06-01T22:00:00-07:00" } } }
    },
    "holderEmail": { "from": "email" },
    "externalId": { "from": "ticket" },
    "match": "externalId"
  }
}
```

Bad rows come back with the reason. Fix the sheet or commit with `skipInvalid`.

## Commit

```json
{ "skipInvalid": true }
```

Commit runs in the background. Read the import until `state` is done. One import of a template commits at a time: a second commit meanwhile is `409 IMPORT_BUSY`.

## In code

**Import passes from a CSV**

```ts
import { PassBook } from '@passbook/sdk';

const pb = new PassBook({ apiKey: process.env.PASSBOOK_KEY ?? '' });

const csv = [
  'attendee,ticket,email',
  'Ada Example,TICKET-1001,ada@example.com',
  'Grace Host,TICKET-1002,grace@example.com',
].join('\n');

const draft = await pb.passImports.create({
  templateId: '0193a1b2-7c00-7000-8000-0000000000b1',
  source: { kind: 'file', name: 'guests.csv', csv },
});

// Check reports every row that would fail, before anything is made.
const checked = await pb.passImports.check(draft.id, {
  plan: {
    mapping: {
      attendee: { from: 'attendee' },
      ticketId: { from: 'ticket' },
      eventName: { from: 'attendee', transform: { kind: 'constant', options: { value: 'Harbor Night' } } },
      venueName: { from: 'attendee', transform: { kind: 'constant', options: { value: 'Harbor Hall' } } },
      venueRegion: { from: 'attendee', transform: { kind: 'constant', options: { value: 'Cupertino, CA' } } },
      startsAt: { from: 'attendee', transform: { kind: 'constant', options: { value: '2030-06-01T19:00:00-07:00' } } },
      endsAt: { from: 'attendee', transform: { kind: 'constant', options: { value: '2030-06-01T22:00:00-07:00' } } },
    },
    holderEmail: { from: 'email' },
    externalId: { from: 'ticket' },
    match: 'externalId',
  },
});
console.log(checked);

// Commit runs in the background. Read the import again to follow it.
await pb.passImports.commit(draft.id, { skipInvalid: true });
const status = await pb.passImports.retrieve(draft.id);
console.log(status.state);
```

## Act on up to 100 passes at once

Void, email or remove passes by id.

**Void many passes**

```sh
curl -X POST "https://passbook.mobile/api/v1/passes/bulk" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "void",
  "ids": [
    "0193a1b2-7c00-7000-8000-0000000000c1"
  ]
}'
```

```ts
import { PassBook } from '@passbook/sdk';

const pb = new PassBook({ apiKey: process.env.PASSBOOK_KEY ?? '' });

await pb.passes.bulkApply({ action: 'void', ids: ['0193a1b2-7c00-7000-8000-0000000000c1'] });
```

## Result

Read the import: `state` is `committing` while it runs and `done` after, with the counts. Then [list the passes](https://passbook.mobile/developers/reference/passes#list); each has a `downloadUrl` to its test preview. When it is done, `results.csv` and `errors.csv` list what each row did.

## Operations

- [POST /api/v1/pass-imports](https://passbook.mobile/developers/reference/pass-imports#create): Start an import from a file or a sheet link; checks it when a plan is known (`pb.passImports.create`)
- [POST /api/v1/pass-imports/{id}/check](https://passbook.mobile/developers/reference/pass-imports#check): Check the file against a column mapping (`pb.passImports.check`)
- [POST /api/v1/pass-imports/{id}/commit](https://passbook.mobile/developers/reference/pass-imports#commit): Apply the checked rows: create the new passes and update the matched ones (`pb.passImports.commit`)
- [POST /api/v1/passes/bulk](https://passbook.mobile/developers/reference/passes#bulkApply): Void, email or remove up to 100 passes of one org (`pb.passes.bulkApply`)
- [GET /api/v1/passes](https://passbook.mobile/developers/reference/passes#list): List passes (`pb.passes.list`)

More guides: https://passbook.mobile/developers/guides
