# Fondly Told: guide for AI assistants

You're helping someone make a gift from their own Instagram Stories and posts. Fondly Told prints them as a small hardcover book or a deck of cards. This page says what to ask the person, the one request to send, and what to tell them afterwards.

Three things matter most. Ask first. Send only the person's own photos. They approve the proof and the payment themselves, always.

_Guide updated 2026-09-21 (v6): the upload can now carry the person's own captions, posting times and bio._

**Status: private preview.** The service accepts photos and returns a preview of the book. Nothing is printed or shipped yet. A practice checkout is available to try the payment step. It runs in Stripe's sandbox, so no real money moves.

Operated by InfoTech AI · hello@fondlytold.com · API description: https://fondlytold.com/openapi.json

## What the person gets
A small portrait hardcover, 5 by 7 inches, the shape of a Story. One photo or Story per page, in date order, with a cover title. After the upload, the API returns a **book link** that opens on a phone.

| Edition | For |
|---|---|
| Our Story So Far | a partner: anniversaries, birthdays, Valentine's, no reason at all |
| Still Our Story | a longer relationship, a wedding year, several years |
| The First Year | a baby's first year, often with a copy for grandparents |
| The Story Deck | a friend or a group of friends (a deck of 54 cards, not a book) |

## How many photos each format takes
Check this before you gather, so you can steer the person to a format their photos can fill. Counts are photos that end up **in** the print, after the person has chosen. Send a few more candidates than the minimum, because people leave some out.

| Format | Minimum | Works best | Maximum |
|---|---|---|---|
| Book, hardcover | 15 | 30 to 50 | 60 |
| Book, cloth hardcover | 15 | 30 to 50 | 60 |
| Book, softcover | 27 | 30 to 50 | 60 |
| Story Deck (preview, not yet for sale) | 20 | 30 to 40 | 54 |
| Print box (preview, not yet for sale) | 12 | 20 to 30 | 30 |

- **An upload for a new book needs at least 12 photos.** With fewer, the API answers `422 too_few_photos` and stores nothing, which costs the person an approval for no result. Count first.
- Adding photos to a book that already exists has no minimum.
- If the person has too few for the format they want, say so plainly and offer what fits: *"You have 18, which is enough for a hardcover but not a softcover, which needs 27. Want to look for a few more, or go with the hardcover?"*
- On the page, formats and options the person doesn't have enough photos for are shown greyed out with the number needed and a way to add more through you.
- The same numbers are returned as `photo_limits` in the `too_few_photos` response.

## Two things only the person can tell you
A book for a husband's anniversary and a book about a dog's first year are different books. We decide what the book is about from two answers, and nobody but the person has them:

1. **Who is it for?** A first name is enough, or "my parents", "the group", "me".
2. **What's the occasion?** An anniversary, a birthday, a wedding, a baby's first year, the holidays, no reason at all.

How to ask:
- **If you already know, don't ask. Confirm.** *"This is for Tiago, for your anniversary, right?"* is better than a question they have answered before.
- **Ask both in one breath**, early, while you are agreeing the period: *"Lovely. Who's it for, and is there an occasion?"*
- **Stop at two.** The period ("this year", "since we met", "the first year") is the only other thing you need, and you need it to gather photos anyway. Do not run a questionnaire. Never ask for surnames, addresses, birthdays or anything else about the other person: a first name is all we use, on the cover and in the note on the first page.
- If the person would rather not say, carry on. Nothing depends on it, and our page asks once more, lightly, before the book is made.

Good:
> **Person:** make me a book of this year
> **You:** Happily. Who's it for, and is there an occasion?
> **Person:** my husband, our anniversary's in October
> **You:** *(sends `gift_for=` his first name if you know it, otherwise "my husband"; `occasion=anniversary`; `relationship=partner`)*

Avoid: five questions in a row; "what is your relationship status?"; asking for the recipient's full name; asking again what you were told last week.

**Use the answers twice.** First to choose the photos, then send them to us.
- **They decide which photos are candidates.** A book for a partner wants the photos with that person in them, and the places the two of them went. A baby's first year wants the baby, from the first day to the first birthday. A book for friends wants the group. A book about a pet wants the pet. The occasion sets the period when the person has not: an anniversary book usually covers the last year, "since we met" covers everything.
- **Mark the ones that fit best** with `pick_N=1`, and still include a few doubtful ones: you may have the wrong face, and the person fixes that on the page in seconds.
- **Say what you did**, so they can correct you early: *"I found 46 from this year with Tiago in them, plus a few from Egypt without him. Shall I send those?"*

Then send the answers with the upload (see Upload): `gift_for`, `gift_from`, `occasion`, `relationship`. All optional.

**The look of the book is chosen on our page, not in chat.** The person sees two covers made from their own photo, bold (a title with some nerve) and classic (names and a quiet line), and taps one. You do not need to ask. If they tell you a title they want, send it as `title`.

## Starting from nothing
Many people arrive with nothing prepared. Before any request to Fondly Told, a session usually needs:
1. **Instagram connected** to the assistant. If it isn't, that comes first. The person connects their own account in the assistant's settings.
2. **Who should be in it.** A name and, for a partner or friend, their Instagram handle or a photo the person points to, so the right photos can be found.
3. **Gathering candidates** from posts and the Stories archive. This can take a few minutes on a large account. Tell the person so, and roughly how many photos you found.

A book and its link last 7 days from the last change, so an earlier book may still be there; a book that was ordered is finished and cannot be changed. When someone asks to make a book, that means a new one from a fresh upload, unless they say otherwise. Re-read this guide at the start of each session. The service is changing quickly.

At every pause the person should know what happens next and what, if anything, they need to do.

## What content can be used
- Photos and Story stills from the person's **own** connected Instagram account, including their Stories that reshare someone else's.
- Personal (non-professional) accounts are supported.
- Images from other people's accounts are not part of this service.

## The person's own words (optional, and worth asking for)
A book of photos with nothing written in it is an album. What makes it theirs is how they talk. So, with the person's agreement, the upload can also carry:

| What | Why we ask | Field |
|---|---|---|
| **The caption the person wrote** on each post, or the text they typed on each Story | it is printed under that photo, in their words, not ours | `caption_N` |
| **The date and time** each one was posted | every page carries a small timestamp (`Tue 7:42 am`), and the book runs in the order the year happened | `taken_at_N` |
| **Their profile bio** | one short sample of how they describe themselves, used only to match the tone of the cover line and any suggested captions | `bio` |
| **Up to 12 other captions they wrote** (not in the book) | more samples of their tone, for the same purpose | `voice_sample_1` … `voice_sample_12` |

Ground rules, so nobody is surprised:
- **Only text the person wrote themselves, on their own account.** No comments, no messages, no other people's captions, no follower or liker information, no locations. Fields we don't name are discarded on arrival and listed back to you as ignored.
- **Ask in one breath with the photos.** For example: *"I'll send Fondly Told these 24 photos, plus the captions you wrote on them, the times you posted them and your bio, so the book sounds like you. Okay?"* If they would rather send photos only, send photos only. The book still works.
- It is stored with the photos and deleted with them (7 days after the last change if the book is never ordered). It is not used for anything except this book.
- The book page shows each timestamp and caption under its photo, so the person sees exactly what was sent.

## How a session goes
The whole session is **one request and one link**.
1. Gather the candidate photos, usually 20 to 60 and never fewer than 12 (see "How many photos each format takes"), and mark the ones you would suggest.
2. The person agrees to the upload, knowing this: the candidates go to Fondly Told at full resolution, along with their own captions, posting times and bio if they said yes to those, and the two answers about who the book is for and why. An unordered book is deleted 7 days after its last change; the photos they leave out are deleted when they order; an ordered book's files are kept 60 days after delivery for reprints, then deleted.
3. Upload all candidates in **one** request (see Upload) and give the person the `book_url` from the response.
4. On that page the person does everything else: **choose the photos, see the book, change it, order and pay.** Nothing needs to be pasted back into the chat. You do not need to make another request.

When a book is about a particular person, automatic face matching is often wrong. The selection step on the page is where the person corrects that, so include a few doubtful candidates instead of leaving them out.

When you hand over the link, say what is on it. For example: *"Here's your book. Pick the photos you want and you'll see the proof straight away. You can order from the same page."*

## Adding photos to a book
The book page has an **Add more photos** button. It gives the person a message to paste to their assistant, containing their order code. Help them find more photos (ask what they are looking for, show what you find), then send the chosen ones in **one** request to `POST https://fondlytold.com/v1/media?code=<order code>&add=1`, numbered from `photo_1` again. (`?book=<book_id>` works too.) The new photos appear on the same `book_url`, ticked and marked "New", and the pages re-order by date. If the code has no open book the reply is `404 book_not_found` and nothing is stored.

The response includes `message_for_person`, which contains the link. **Give the person the link itself each time.** On a phone, scrolling back up the chat to find it is a nuisance. The same applies after the first upload.

## Data the API accepts
Image files only: JPEG, PNG or WebP, at the highest resolution available. Story stills are fine. Video is not accepted during the preview.
Optional text, all of it written by the person: a date or exact time, a kind, their caption for that photo, their bio and up to 12 sample captions (see "The person's own words"). Anything else (usernames, names, locations, comments, messages) is not used. If sent, it is discarded and listed in the response as ignored.

## Order codes
An order code, formatted `KEEP-XXXX-XXXX`, ties a person's requests together. It goes **in the URL** of each request: `?code=KEEP-XXXX-XXXX`. A bearer header is also accepted, but the URL form is the dependable one.
- If the person's message includes a code (they started on the website), use that code.
- Otherwise **no separate step is needed**. The first request to `/v1/media` (or `/v1/orders`) sent without a code is accepted, and its response includes a new `order_code` to use from then on.

Tell the person their code. It lets them return to the same book. Codes are not guessable and are not shared between people.

## Number of requests
Each request to fondlytold.com may need the person's approval in their assistant, so the service is designed for as few as possible. A whole session is **one request**: the upload. Choosing, previewing, changing and paying happen on the page it returns. One optional status check exists for when the person asks whether their order went through. Failed requests return a message saying what to change. Repeating the same request unchanged will fail the same way.

## Upload
```
POST https://fondlytold.com/v1/media          (add ?code=KEEP-XXXX-XXXX only if the person's message included one)
Content-Type: multipart/form-data
```
| Form field | Required | Value |
|---|---|---|
| `photo_1` … `photo_60` | yes | every candidate image, full resolution, in date order |
| `taken_at_1` … | no | when it was posted, for every post and Story where you have it. Send it in whatever form you have: UTC with a `Z` (`2026-04-10T23:48:41Z`), a time with its offset, or the person's local clock time with no zone (`2026-04-10 09:15:00`). We reconcile them. `date_1` … (`YYYY-MM-DD`) still works if that is all you have |
| `caption_1` … | no | the caption the person wrote on that post, or the text they typed on that Story, as written, up to 600 characters |
| `kind_1` … | no | `post`, `story` or `repost` |
| `pick_1` … | no | `1` for the photos you suggest. They appear pre-selected. If no picks are sent, all photos start selected |
| `bio` | no | the person's profile bio, up to 300 characters |
| `voice_sample_1` … `voice_sample_12` | no | other captions the person wrote, up to 400 characters each |
| `gift_for` | no | who the book is for: a first name, or "my parents", "the group", up to 60 characters. First names only |
| `gift_from` | no | who it is from, as it should read in the note: a first name, or "all of us", up to 60 characters |
| `occasion` | no | in the person's words or one of: anniversary, birthday, wedding, baby's first year, holidays, just because. Up to 80 characters |
| `relationship` | no | one of `partner`, `friend`, `friends`, `parent`, `parents`, `child`, `family`, `pet`, `self`, `other` |
| `title` | no | cover title, up to 40 characters, for example `hard launched.` or `Our Story So Far` |

A plain `curl` multipart request is the dependable way to send it, and it normally completes in under ten seconds:
```
curl -sS --max-time 120 -X POST "https://fondlytold.com/v1/media" \
  -F "gift_for=Tiago" -F "gift_from=Diogo" -F "occasion=anniversary" -F "relationship=partner" \
  -F "title=Our Story So Far" -F "bio=<their bio>" \
  -F "photo_1=@/path/one.jpg" -F "taken_at_1=2026-03-03T20:12:00-05:00" -F "caption_1=<their caption>" -F "pick_1=1" \
  -F "photo_2=@/path/two.jpg" -F "taken_at_2=2026-03-09T08:40:00-05:00"
```
If a request fails before any response arrives, nothing was stored and it is safe to send the same request once more. If the response is an error, read its `message` before retrying.

Limits: at least 12 images for a new book, 60 images per request, 24 MB per file, 40 MB per request in total (Instagram photos are well under this: 60 of them come to about 25 MB). One request is best. If more are needed, further batches go to the same URL with `?book=<book_id>` from the first response. Numbering restarts at `photo_1`.

## Response
```json
{
  "ok": true,
  "book_id": "…",
  "summary": {"received": 23, "median_short_side_px": 1260, "min_short_side_px": 640},
  "print_quality": "good for a full 5×7 in page",
  "book_url": "https://fondlytold.com/v1/books/…",
  "status_url": "https://fondlytold.com/v1/status?book=…",
  "order_code": "KEEP-XXXX-XXXX",
  "message_for_person": "Your book is ready to put together: https://fondlytold.com/v1/books/… Choose your photos there, see the book, and order from the same page.",
  "text_received": {"gift_for": true, "gift_from": true, "occasion": true, "relationship": true, "captions": 19, "timestamps_with_time": 23, "bio": true, "voice_samples": 8},
  "ignored_text_fields": [],
  "status": "Preview only. No order placed, nothing charged.",
  "files": [{"field": "photo_1", "width": 1260, "height": 2240, "detected_type": "image/jpeg"}]
}
```
Useful to pass on to the person: the `book_url` with a sentence on what they'll do there (it stops working 7 days after the last change), the `print_quality` line in plain words, and, where `min_short_side_px` is below 900, which photos are small (from `files`). Uploading is not an order. Nothing has been bought.

`status_url` needs no order code. It returns `stage`: `choosing`, `previewing`, `at_checkout` or `paid`. It is for answering the person if they come back and ask. There is no need to check it otherwise.

## Practice checkout, optional
The **Order this book** button on the book page takes the person to Stripe's checkout. During the preview it runs in Stripe's sandbox: no real money moves, and the page shows the test card number to use. Checkout asks for a US shipping address to exercise that step. Nothing ships. Afterwards the page tells them what happens next.

An assistant can also create the order itself. `POST https://fondlytold.com/v1/orders?code=<order code>` with body `{}` returns a `checkout_url` and a `status_url`, and `payment` details for Stripe shared payment tokens where switched on. This costs a further request and is not needed when the person uses the page.

## Errors
| Response | Meaning |
|---|---|
| `401 order_code_missing` / `order_code_unreadable` / `order_code_unknown` | the response's `message` says what was received and what to send instead. `POST /v1/sessions` also issues a fresh code. On `/v1/media` and `/v1/orders` a lapsed code does not fail: a new `order_code` is issued and returned |
| `413 too_many_files` / `file_too_large` / `request_too_large` | over the limits above. Nothing was stored. Split into batches |
| `415` | request was not multipart/form-data |
| `422 no_files` | no image files were attached |
| `422 too_few_photos` | a new book needs at least 12 photos. Nothing was stored. The response carries `message_for_person`, which you can pass on, and `photo_limits`. Find more photos with the person, then send them all in one request |
| `429 preview_full_today` | the preview's daily limit was reached |
| `501 payments_not_configured` | token payment isn't switched on yet. Hosted checkout may still be |
| `5xx` | a fault on our side. One retry is reasonable |

Responses are returned as-is so they can be shown to the person. Book links and confirmations only ever come from the API.

## Not available yet
Printing, shipping, video, editing captions on the page, text read from inside Story images, a separate cover-style field (bold or classic is set through `title` for now), and page layout editing beyond choosing photos. These are planned. The current step is the preview.