# Candid Beacon - integration guide

Candid Beacon publishes a freelancer's real availability as a public page, an
embeddable badge and a share card. This file describes everything a third party
can embed. It is the complete public surface; nothing here requires an account,
an API key or any credential.

Replace YOUR_USERNAME with the freelancer's Candid Beacon username throughout.

## The embeddable badge

A small pill showing current availability and, when one is known, the next
opening date. Paste this where the badge should appear:

<iframe src="https://app.candidbeacon.com/embed/badge?u=YOUR_USERNAME" title="Availability status" loading="lazy" style="width:100%;max-width:448px;height:48px;border:0;overflow:hidden"></iframe>

- Width is fluid up to 448px; height is fixed at 48px.
  These are the badge's measured intrinsic size - the pill is 44px tall in every
  state, and 48px leaves room for the one-line wrap that happens on
  host pages narrower than about 320px.
- The badge is designed to be framed on any origin and sets its own framing
  policy for that purpose. No other page on the app permits framing.
- It needs no script on the host page and sets no cookie.
- An unknown or unpublished username renders a neutral badge, never an error.
- Availability is carried by a word and a distinct shape as well as by colour,
  so the badge does not rely on colour alone.

## The public Beacon page

    https://app.candidbeacon.com/beacon/YOUR_USERNAME

The full availability page: current status, a capacity reading, and the next
opening date when one is known. Server-rendered, so it can be linked, crawled
and unfurled without running JavaScript.

## The share card

    https://app.candidbeacon.com/beacon/YOUR_USERNAME/og-image

A 1200x630 image for link previews. The Beacon page already references it in its
own Open Graph tags, so linking to the page is normally enough; fetch this
directly only if you are building a preview yourself.

## Dates

Next-opening dates describe the FREELANCER's availability and are deliberately
NOT converted into the reader's timezone - converting them would display a day
the freelancer is not actually free on. They are rendered as an unambiguous
day-month-year ("3 Sep 2026") and carry a machine-readable value in a
<time datetime="YYYY-MM-DD"> element with no time and no offset. Do not
reformat them into an all-numeric form: "03/09/2026" is read as two different
dates in two different places, which is the ambiguity this format exists to
avoid.

## What is not here

There is no public write API, no way to read a freelancer's jobs, clients,
capacity inputs or contact list, and no endpoint that accepts a credential. If
an integration seems to need one of those, it is not something this product
exposes.