01What it does
The Recapply API makes private recap links. You send people (a first name and their numbers), and get back one link per person, in your company's brand. Then you send each link however you like: email, text, your app.
- It works with Zapier and Make, so you can connect 6,000+ apps without code.
- It only makes links. We keep each person's first name (scrambled) and simple counts (opened, shared, saved) so your People page works. We do not keep their numbers, email or phone, and the API can't list, read or change them later.
- Your template, colors and words come from your saved brand. A request can pick a year or month recap, how long links stay open, the language, and (with
style) how the links look. You can set your logo with/api/v1/logoand make recaps in its colors; photos stay in the dashboard.
02Your API key
A company admin makes keys in the dashboard under Developers. A key looks like rc_live_… and is shown once: copy it then. You can have up to 5 keys and revoke any of them at any time.
Send it on every request as a header:
Authorization: Bearer YOUR_API_KEYKeep keys on a server or in Zapier or Make. Never put one in a web page or app that people download: anyone with the key can make links for your company.
03Test your key
GET /api/v1/me says which company the key belongs to and its plan. Use it as the “test connection” step.
curl http://localhost:3000/api/v1/me \
-H "Authorization: Bearer YOUR_API_KEY"{
"company": {
"name": "Acme Fitness"
},
"plan": {
"id": "starter",
"name": "Starter",
"status": "active",
"monthlyRecaps": 10000
},
"planRequired": true,
"key": {
"name": "Zapier",
"createdAt": "2026-10-23T09:00:00.000Z"
}
}04Your fields
GET /api/v1/template lists the numbers your recap expects: each one's header (the name to send), its label, whether it's a whole number or a decimal, and its allowed range. They follow your template on the Brand page, so check here after you change it.
{
"template": "coding",
"name": {
"field": "name",
"required": true,
"max": 20
},
"stats": [
{
"header": "commits",
"key": "commits",
"label": "Commits",
"type": "integer",
"min": 0
},
{
"header": "top_percent",
"key": "pct",
"label": "Top percent (1–100)",
"type": "integer",
"min": 1,
"max": 100
}
],
"maxPeoplePerRequest": 500
}05Make links
POST /api/v1/links with a JSON body. Send up to 500 people at once:
curl -X POST http://localhost:3000/api/v1/links \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"people":[{"name":"Noah","role":"Team lead","email":"noah@example.com","stats":{"commits":1627,"projects":21,"longest_streak":77,"top_percent":5}}]}'name: first name, up to 20 characters. Required.stats: every field from/template, by its header. Numbers or numbers as text (“1,627” works).role: job or team, shown under the name. Optional.email,phone: optional. Checked and handed back with the link for your next step. We never contact anyone.
One person, flat (easiest in Zapier): put the name and stats side by side, and you get a url at the top of the reply.
{
"name": "Noah",
"email": "noah@example.com",
"commits": 1627,
"projects": 21,
"longest_streak": 77,
"top_percent": 5
}The reply has one entry per person, in the order sent:
{
"made": 1,
"failed": 0,
"links": [
{
"name": "Noah",
"ok": true,
"url": "http://localhost:3000/r/e1.xRNojU0epHPV5tleUiQ…",
"email": "noah@example.com"
}
]
}A person with a problem gets ok: false and an error in the same words as a spreadsheet upload (for example commits: Missing a number). Everyone else still gets a link. A bad email or phone is dropped with a warning; the person still gets a link. Links you make count toward your plan, just like links made in the dashboard.
// On your server only: never put the key in a web page.
const res = await fetch("http://localhost:3000/api/v1/links", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.RECAPS_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"people": [
{
"name": "Noah",
"role": "Team lead",
"email": "noah@example.com",
"stats": {
"commits": 1627,
"projects": 21,
"longest_streak": 77,
"top_percent": 5
}
}
]
}),
});
const { links } = await res.json();
// links[0].url is Noah's private recap linkA year or a month. Each recap covers what your brand says: the whole year, or one month. To choose for one request, add these next to people (or next to the name in a flat body):
period:"year"or"month". Optional.month: 1 to 12, or the name, like10or"October". Optional. A month on its own means a monthly recap. Without it, a monthly recap uses your brand's month, or else last month. The year is your brand's year.
Run it once a month (a Zapier schedule works) and everyone gets a fresh recap of their month.
{
"period": "month",
"month": 10,
"people": [
{
"name": "Noah",
"stats": {
"commits": 1627,
"projects": 21,
"longest_streak": 77,
"top_percent": 5
}
}
]
}Anything else, like "month": 13 or a month with "period": "year", is a 400 invalid_body with the field named in details.
Links that stop opening. Links stay open as long as your brand says (“Links stay open”: forever unless you change it). To choose for one request, add expiresInDays: a whole number from 1 to 730. After that many days the link shows “not found”, just like a link you switch off. Anything else is a 400 invalid_body.
{
"expiresInDays": 30,
"people": [
{
"name": "Noah",
"stats": {
"commits": 1627,
"projects": 21,
"longest_streak": 77,
"top_percent": 5
}
}
]
}Language. Recaps print in your brand's “Recap language” (English unless you change it): the story pages, the card, the share text and the saved images. To choose for one request, add lang (or language): "en", "es", "fr", "de", "pt" (Brazilian Portuguese), "it", "nl" or "ja". Region codes like "pt-BR" or "de-DE" work too. Anything else is a 400 invalid_body. Names, stat labels and your own words print as you wrote them.
{
"lang": "de",
"people": [
{
"name": "Noah",
"stats": {
"commits": 1627,
"projects": 21,
"longest_streak": 77,
"top_percent": 5
}
}
]
}Compared to last time. Send last month's (or last year's) numbers too, and the recap gets one extra page before the back cover: “+23%”, “186 workouts vs 151 in September”, for up to three stats. Optional, any stat from /template except top_percent, checked like the stats. Leave them out and the recap is exactly as before.
- With
people: aprevobject next tostats, by the same headers. - Flat: the header with
prev_in front, likeprev_commits, next to the stats.
{
"people": [
{
"name": "Noah",
"stats": {
"commits": 1627,
"projects": 21,
"longest_streak": 77,
"top_percent": 5
},
"prev": {
"commits": 1290
}
}
]
}{
"name": "Noah",
"commits": 1627,
"projects": 21,
"longest_streak": 77,
"top_percent": 5,
"prev_commits": 1290
}06Change how links look
Links look like your saved brand. To change the look for one request, add a style object next to people. To change it for one person, put style inside that person: their own values win over the request's. Leave style out and nothing changes. Each value is checked and limited exactly like the Brand page, and only things that are safe to carry in a link are allowed (no logo, no photo, no image address). A wrong value is a 400 invalid_body for the request's style, or ok: false with the field named (like people[1].style.font) for one person.
| Field | Type | What it does |
|---|---|---|
| colorway | integer | string | A preset color set of your template: its index or its id (see colorways). Replaces your own brand colors for this link. |
| colors | object | Your own two colors: { "main": "#2747e8", "accent": "#ffb81c" }. Use either colorway or colors. |
| font | string | Font style. One of: magazine, modern, playful. |
| cover | string | Cover layout. One of: classic, big, center. |
| texture | string | Page texture. One of: none, grain, dots, lines. |
| round | boolean | Rounded corners on bars, squares and the barcode. |
| outline | boolean | Big numbers drawn as outlines. |
| rarity | boolean | false makes plain cards with no rarity tier (no Common to Legendary badge, chart or foil). Default: your saved brand's setting. |
| footer | string | A short line at the bottom of every inside page. Up to 32 characters. |
| barcode | boolean | false hides the barcode on the covers. |
| sticker | string | A sticker on the cover. One of: none, star, heart, bolt, sparkle, smile. |
| badge | string | Letters in a round badge on the cover. Up to 3 characters. |
| animation | string | How pages turn in the story. One of: smooth, flip, zoom, stack, liquid, glitch, confetti. |
| headline | string | Cover headline. Up to 60 characters. |
| signoff | string | Back cover message. Up to 80 characters. |
| about | string | A few lines about your company, small on the back cover. Up to 280 characters. |
| ink | string | Text color as #rrggbb, or "" for automatic. Kept readable: a color that would be hard to read is moved to the nearest shade that reads, and you get a warning. |
| paper | string | Page color as #rrggbb, or "" for automatic. Same readability guard as ink. |
| background | object | Generated artwork behind the pages and the card: { "mode": "art", "seed": 0-9999, "palette": [2 to 5 #rrggbb colors] }, or { "mode": "off" }, or { "mode": "ai" } to use your saved AI art set (a different picture of it per person; needs AI art switched on and a set made on the Brand page; it never makes new pictures, so it costs nothing). Photos are dashboard-only; set a logo with POST /api/v1/logo. |
| personalLine | string | Only inside a person's own style. Your own line for that person, in place of the cover headline under their name. Links, @ and < > are removed. Up to 120 characters. |
{
"style": {
"font": "modern",
"cover": "big",
"colors": {
"main": "#2747e8",
"accent": "#ffb81c"
},
"sticker": "star",
"background": {
"mode": "art",
"seed": 7,
"palette": [
"#3b5bdb",
"#c2255c"
]
}
},
"people": [
{
"name": "Noah",
"stats": {
"commits": 1627,
"projects": 21,
"longest_streak": 77,
"top_percent": 5
},
"style": {
"personalLine": "Noah shipped more than anyone this year."
}
},
{
"name": "Mei",
"stats": {
"commits": 1627,
"projects": 21,
"longest_streak": 77,
"top_percent": 5
},
"style": {
"sticker": "heart",
"background": {
"mode": "off"
}
}
}
]
}Your own words per person. personalLine is your own sentence for that person (up to 120 characters). Write it in your system, or with your own AI, and send it here: we use it as you wrote it, and only remove links, @ and < >. It shows under their name and on their card, instead of the cover headline.
AI art set. A company that turns on AI art on its Brand page gets a small saved set of backgrounds made from its colors."background": { "mode": "ai" } gives each person one picture of that set (the same person always gets the same one). It only uses the saved set and never makes new pictures, so it costs nothing and never changes your bill. Without a saved set, or with AI art off, the link keeps your saved look.
Readable colors. If your ink (text) color would be hard to read on the page, it is drawn as the nearest shade that reads, and the person's warning says so.
GET /api/v1/style returns this list as data, your template's color sets (with the index and id to send as colorway), the limits and your current look, so you can build a picker.
curl http://localhost:3000/api/v1/style \
-H "Authorization: Bearer YOUR_API_KEY"07Make recaps from your logo
Send your logo and we find its main colors, then give you a ready-made style to paste into POST /api/v1/links. This is plain color matching from the picture, not AI: the same logo always gives the same colors. You can look first, or save the logo as your company logo.
POST /api/v1/logo/previewlooks at a logo and saves nothing.POST /api/v1/logosaves it as your company logo (the old file is deleted). Add"place"(cover,card,both,pagesoroff) to choose where it shows (pagesis the cover, a small logo on every inside page, and the card). Add"applyLook": trueto also save its main and accent colors as your brand colors. Add"applyLook": "full"to match your whole brand to the logo in one step: those colors, the logo on every page (unless you send aplace) and your logo's shape as the background look. A full match replaces your saved background. Nothing else of your brand changes.GET /api/v1/logoreturns the current logo link, where it shows and its colors.DELETE /api/v1/logoremoves it.- Replies:
POST /api/v1/logoanswers201withlogo,palette,lookandstyle, pluslogoUrl,placeandapplied(what was changed, such as"logo","place","colors.main"). A full match also addsbackground(modeismark, orartwhen no clear shape could be cut out of the logo, plusseedandpalette) and"background.mark"or"background.art"inapplied.GETanswers{ "logoUrl", "place", "look" }, wherelookis the same object preview returns (so the colors are atlook.look.colors), or all three arenullwhen there is no logo.DELETEanswers{ "removed": true }, or{ "removed": false, "message" }when there was no logo.
Send one of: { "url": "https://…/logo.png" } (a public https link), { "base64": "…" } (a data: link works too), or a form with a file field. PNG, JPG or WebP, up to 512 KB and 2000 x 2000 pixels. SVG is not accepted. The file type is read from the file itself. The body can be up to 800 KB. Logo requests are limited to 12 a minute per company.
The reply has logo (size and type), palette (2 to 5 colors found), look (colors main and accent, an artwork background, and short notes; sometimes a suggested ink text color) and style, which you can send as it is. A black, white or grey logo gets a calm silver and grey pair. A white mark on a colored square uses the square's color. The saved logo shows on the cover and card of the links you make, and recaps without a style use your saved brand.
curl http://localhost:3000/api/v1/logo/preview \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/logo.png" }'curl http://localhost:3000/api/v1/logo \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/logo.png", "place": "both", "applyLook": true }'curl http://localhost:3000/api/v1/logo \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/logo.png", "applyLook": "full" }'curl http://localhost:3000/api/v1/logo/preview \
-H "Authorization: Bearer YOUR_API_KEY" \
-F file=@logo.png08Errors
Errors always look like { "error": { "code": "…", "message": "…" } }. Check the code; the message is written for people and may change.
09Limits
- 500 people per request, and a body up to 256 KB.
- 60 requests a minute per key. After 20 wrong keys from one address, that address waits 10 minutes.
- Your plan's monthly recaps apply. One link for one person is one recap.
- 5 keys per company.
- Logo requests: 12 a minute per company, a body up to 800 KB, and a logo file up to 512 KB.
10Logo recipe
Make a whole batch of recaps in your logo's colors, in three calls.
- Look at your logo first. This saves nothing. The reply has a
stylewith your logo's main and accent colors and a matching background. It is color matching from the picture, not AI.Step 1: look at the logo curl http://localhost:3000/api/v1/logo/preview \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/logo.png" }' - Save it as your company logo, and keep its colors as your brand colors with
applyLook. LeaveapplyLookout to keep your colors as they are. Use"applyLook": "full"instead to also put the logo on every page and use its shape as the background.Step 2: save the logo curl http://localhost:3000/api/v1/logo \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/logo.png", "place": "both", "applyLook": true }' - Make links with the style from step 1 (or leave
styleout to use your saved brand):Step 3: make links curl http://localhost:3000/api/v1/links \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "style": <the "style" from step 1>, "people": [ { "name": "Noah", "stats": { "commits": 1627 } } ] }'
Your logo can be a PNG, JPG or WebP up to 512 KB. To remove it later, send DELETE http://localhost:3000/api/v1/logo.
11Zapier recipe
For example: a new row in Google Sheets, or a new customer in Stripe, gets their recap link by email.
- In Zapier, make a Zap. Pick the trigger: where new people come from. For example Google Sheets → New Spreadsheet Row, Stripe → New Customer, or HubSpot → New Contact.
- Add an action: search for Webhooks by Zapier and choose the event POST.
- URL:
http://localhost:3000/api/v1/links. Payload Type:Json(Formworks too). Leave Wrap Request In Array onNo. - Data: add one row per field and map each to your trigger's value:
name,commits,projects,longest_streak,top_percent. Optional:role(job or team) andemail, which comes back with the link for your next step. - Headers: key
Authorization, valueBearer YOUR_API_KEY(your key from Developers in the dashboard). - Test the step. You get back a
url: that person's private recap link. - Add one more action to send it, for example Gmail → Send Email or Twilio → Send SMS, and put the
Urlfrom the webhook step in the message.
Zapier's own guide: Send webhooks in Zap workflows.
12Make recipe
The same in Make, with the HTTP app.
- In Make, start a scenario with the app your people come from, for example Google Sheets → Watch New Rows or Shopify → Watch Orders.
- Add the HTTP app's Make a request module.
- URL:
http://localhost:3000/api/v1/links. Method:POST. - Headers: name
Authorization, valueBearer YOUR_API_KEY. - Body content type:
application/json. Choose JSON string as the input method and paste this into the body, then swap each{{1.…}}for the matching value from your first module:Body to paste into Make { "people": [ { "name": "{{1.name}}", "email": "{{1.email}}", "stats": { "commits": "{{1.commits}}", "projects": "{{1.projects}}", "longest_streak": "{{1.longest_streak}}", "top_percent": "{{1.top_percent}}" } } ] } - Turn on Parse response, run once, and use
links[1].url(Make counts from 1) in your email or message module.
Make's own guide: HTTP app.
13Embed in your app
Put each person's recap inside your own app or site, so they see it without an email. Make the link with the API, then show it with one button.
- Make the person's link on your server with
POST http://localhost:3000/api/v1/links, the same call as above. The reply has aurlfor each person. Keep it on your server and hand it to the page only for the person who is signed in. - Add our script once (any page that shows the button), then add a button with that person's link. A tap opens their recap full screen on a phone, and as a card on a big screen.
A button <button type="button" data-recapply-link="http://localhost:3000/r/PERSON_RECAP_LINK">See my year</button> <script src="http://localhost:3000/embed.js" async></script> - Or open it from your own code, for example after your app fetches the link.
From your code <script src="http://localhost:3000/embed.js" async></script> <script> // After you fetch the person's link from your server: document.getElementById("see-my-year").addEventListener("click", function () { window.Recapply.open("http://localhost:3000/r/PERSON_RECAP_LINK"); }); // Optional: run something when the person closes the recap. window.addEventListener("recapply:close", function () {}); </script> - Or put the recap in a box on your page. Use
/embed/and the token from the end of the link (the part after/r/). Only this address can be shown in a box on other sites.A box on your page <iframe src="http://localhost:3000/embed/PERSON_RECAP_LINK" title="Your year in review" allow="clipboard-write; web-share" referrerpolicy="no-referrer" style="width:100%;max-width:420px;height:720px;border:0;border-radius:16px" ></iframe> - Optional: hear when it is ready or closed. The box sends two short messages with no names, numbers or links in them. The script above handles this for you.
Listen to the box window.addEventListener("message", function (e) { if (e.origin !== "http://localhost:3000") return; if (e.data && e.data.type === "recapply:close") { /* hide your box */ } if (e.data && e.data.type === "recapply:ready") { /* the recap has loaded */ } });
- The script only opens secure (https) recap links from localhost:3000. Any other address is ignored.
- The person can close it with the Close button or the Esc key. The page behind stays put and does not scroll.
- A link that was switched off or has run out shows a short "This recap isn't available" message.
- No cookies. Opens, shares and saves still count on your People page.
14Privacy and security
- We keep only a fingerprint (hash) of each key, never the key itself.
- The people you send are turned into links. We keep only each first name (scrambled) and simple counts, not numbers, email or phone. We don't log request bodies or keys.
- Each link carries that one person's name and numbers, signed so nobody can change them. Anyone with a link can open it, so send it only to that person.
- Revoking a key stops it within about 30 seconds, usually at once.