Per-photo data with a CSV

This article shows you how to upload a CSV to a flow's Photos step so each photo carries its own data — player name, jersey number, team, or any other field — that downstream steps can insert into rendered images automatically. (Beta)

What the CSV does

When you run a flow, every photo goes through the same pipeline. Without a CSV, all photos share whatever text you typed into a step's fields. With a CSV, each row describes one photo: the filename column matches the row to a photo, and every other column becomes a variable — a {Player First}, {Jersey}, or {Team} token that create steps can substitute per photo.

Matching is case-sensitive and exact: player1.jpg matches the row whose filename value is player1.jpg. Photos that have no matching row render using the literal text you typed in that field (or blank, if the field contained only a token).

Download the sample CSV

Before uploading your own file, grab the built-in example so you can see the required format:

1. Open the Flows tab and open (or create) a flow.
2. Select the Photos start step to open its configuration panel on the right.
3. Under Data CSV, click Download sample CSV.

The downloaded file (flow-sample.csv) opens in any spreadsheet app. It looks like this:

The filename column is required and must be the first column. Add as many additional columns as you need — their header names become variable names.

Prepare your CSV

Rules to follow before uploading:

• The first column must be named filename exactly (lowercase).
• Each value in filename must match the uploaded photo's filename exactly, including the file extension (.jpg, .png, etc.).
• One row per photo. Extra rows that don't match any photo are ignored.
• Save the file as CSV (comma-separated). UTF-8 encoding is safest for names with accents or special characters.
• Column header names become the variable names you see in the {variable} picker — keep them short and descriptive (e.g. Jersey, not Player Jersey Number on Back of Uniform).

Upload the CSV to the Photos step

1. Select the Photos start step. Its configuration panel opens on the right.
2. Add your photos first using Add photos if you haven't already — the match preview won't show until photos are present.
3. Under Data CSV, click Add CSV and choose your file.
4. The panel shows a summary: number of rows loaded and which column names were found. If photos are already in the step, a match count appears — for example, 3 matched or 2 matched · 1 unmatched.

An amber unmatched count means one or more photos don't have a corresponding row in the CSV. Those photos still run through the flow — they just won't have per-photo data for that field. Fix unmatched photos by checking that the filename values in your CSV exactly match the filenames of the uploaded photos.

To swap out the file later, click Replace. To remove the CSV entirely, click Remove CSV.

Use CSV columns in create steps

Once a CSV is loaded, every text field in downstream create steps gains a {} button. Click it to open the variable picker and choose a column to insert as a token. The token appears in the field as {Column Name}.

1. Select a Create Image or Create Editable Image step.
2. Click a text field — for example, the field mapped to your template's Name layer.
3. Click the {} button at the right edge of the field.
4. Pick the column you want — for example, Player First.
5. The token {Player First} is inserted. Combine tokens and literal text freely: {Player First} {Player Last} or #{Jersey}.

If you type a token by hand and the column name doesn't match anything in the CSV, the field shows an amber warning: "{Token}" isn't in your CSV — it will be blank. Fix the typo or pick the variable from the picker instead.

When the flow runs, each photo resolves its row and the tokens are replaced with that row's values before the image is rendered. The result is a unique rendered image for every player — all from a single flow run.

Related articles

• What is Flow? (automation pipelines)
• Building your first flow
• Flow step reference
• The {variable} picker
• The Text transform step