Collection examples

A collection is a reusable set of structured entries that many profiles or jobs can point at. You define the collection's fields once — a summary, a category, a website, an uploaded file — then add entries such as Annual leave or TypeScript. A profile or job selects entries by reference, so editing one entry updates every place that selected it. Each selection can also carry its own typed details, so a shared entry stays shared while a company or candidate records what is specific to them.

Collections live in three places. The dashboard is where you create collections, add entries, import CSV files, and connect a collection to the company profile, talent profile, or job form. The public API and the Board SDK return the resolved entries on company, talent, and job responses, and expose the active choices for filters. Cavuno-hosted boards do not render collection fields — an AI-builder site or your own custom frontend does, which is why each example below ends with SDK code and a prompt you can paste into the AI website builder.

Employee benefits

Why

Every company on the board describes the same handful of benefits in slightly different words, which makes them impossible to compare or filter. Hold one Annual leave entry with a neutral description, then let each company attach its own allowance and wording. The same collection powers a "Benefits" section on job pages.

Fields

Every entry also has the built-in name. Add per-selection details on the profile field, not here: days_per_year (Number) and notes (Short text) belong to the company that selected the entry.

Sample entries

Open the collection, choose Import CSV, match name to the entry name, external_id to the external ID, and the rest to their collection fields. Re-importing the same external_id updates that entry instead of creating a second one.

Connect it

1. Open Settings → Company profile → Custom fields → Add field.
2. Choose Collection reference, label it Employee benefits, and check the derived key benefits.
3. Select the Employee benefits collection, choose Multiple, and set Maximum selections — an operator-defined maximum, up to 100. It defaults to 100 and stays editable later.
4. Set summary as the description attribute and turn on Allow title and description changes so a company can say "Flexible annual leave" in its own words.
5. Add Details per selection: days_per_year (Number) and notes (Short text).
6. Leave Show on public profile on and Profile owner can edit on, so approved company members maintain their own benefits.
7. Save, then repeat in Settings → Job form → Custom fields → Add field → Collection reference with the same collection if job pages should list benefits too. Set Default description to summary and, under What each job can change, turn on Allow title and description changes so one job can word a benefit its own way.

What the API returns

A company detail response carries one resolved object per selected entry in objectReferences:

title and description are already resolved: they hold the override when the company set one and the collection default otherwise. titleOverride and descriptionOverride are present only when the company replaced the shared wording.

Render it with the SDK

Ask the AI builder

Add a "Benefits" section to the company profile page. Read objectReferences from the company detail response and keep the selections whose fieldKey is benefits. Render each one as a card with its title, its description, its logoUrl when present, and a "25 days" style pill built from values.days_per_year when that number is set. Keep the order the API returns and hide the section when there are no benefits.

Word a benefit for one job

A job that offers unlimited leave can still select the shared Annual leave entry, so it filters with every other job, and show it as Unlimited PTO. In the dashboard job form, select Annual leave, press its edit button, set Title to Unlimited PTO and Description to "Take the time you need, with a two-week minimum.", then choose Apply changes and save the job. Restore defaults clears both boxes.

Through the API, send the same wording as collectionOverrides next to collectionValues, on the operator job endpoints or on an approved employer's company job endpoints:

The job response then resolves the entry to that wording, while name keeps the shared entry name:

An entry without its own wording returns its name as title, the summary value as description, and null for both overrides. On an update, leave collectionOverrides out to keep the stored wording, or send [] to restore every default.

Technologies

Why

A shared technology list gives every company and candidate the same spelling and the same logo, and it gives the board a filter that actually matches. One entry holds the logo, so no frontend keeps a second technology-to-logo map.

Fields

The entry name is the display name and the image in the logo field is the icon. Put the per-profile nuance on the profile field: years (Number) for companies, proficiency (Single select) for candidates.

Sample entries

Images cannot be imported, so upload each logo in the entry editor after the import. Use a square SVG or PNG so it reads well as a small chip.

Connect it

1. Open Settings → Company profile → Custom fields → Add field → Collection reference.
2. Label it Technologies, key technologies, and select the Technologies collection.
3. Choose Multiple, set Maximum selections to 12 so a stack list stays readable, add the per-selection detail years (Number), and keep Show on public profile and Profile owner can edit on.
4. Save, then open Settings → Talent profile and add the same field with key technologies, Multiple, and a per-selection detail proficiency (Single select).
5. Keep both public: a private field is excluded from public responses and cannot be used as a filter.

What the API returns

Render it with the SDK

The talent directory takes the same clause shape:

Filter options come from board.profileFields.retrieve('company') (or 'candidate'), which returns only public definitions. Submit the record id from choices, never the display name. Follow nextCursor to load more choices.

Ask the AI builder

Build a technology filter for the company directory. Load the options with board.profileFields.choices('company', 'technologies', { search, limit: 20 }), follow nextCursor when the user scrolls, and show each option's name with its logoUrl. When options are selected, pass their id values to board.companies.search as objectReferences: [{ key: 'technologies', recordIds }]. On the company profile, render the technologies selections as logo chips with the years from values.years.

Certifications

Why

Candidates hold the same certification with different issuers, different dates, and sometimes more than one award of it. A shared entry keeps the certification's name and awarding body accurate, while repeatable details record each award the candidate actually holds.

Fields

Issuer and expiry date are not collection fields. They differ per candidate and per award, so they belong in Repeatable details on the profile field.

Sample entries

Connect it

1. Open Settings → Talent profile → Custom fields → Add field → Collection reference.
2. Label it Certifications, key certifications, and select the Certifications collection.
3. Choose Multiple, leave Maximum selections at 20, and add Repeatable details: issuer (Short text, required) and expiry_date (Date).
4. Leave Show on public profile and Profile owner can edit on. The candidate maintains the list and it appears on the public talent profile.
5. For an operator-verified variant, add a second collection-reference field — label Verified certifications, key verified_certifications, the same collection — with Show on public profile off and Profile owner can edit off. Only your team can set it and it never reaches a public response.

Visibility and owner editing are independent. A private field is omitted from public profiles, public API responses, and filters, but the operator still sees it in the dashboard.

What the API returns

verified_certifications is absent from this response because the field is private.

Render it with the SDK

The signed-in candidate edits the same data through board.me.profile.retrieveObjectReferences() and board.me.profile.updateObjectReferences({ selections }). Each repeatable row needs a stable key that starts with a letter — reuse it when editing the same award.

Ask the AI builder

On the talent profile page, add a "Certifications" list built from the objectReferences entries whose fieldKey is certifications. For each selection, show title and attributes.awarding_body, then one row per item in entries with values.issuer and a formatted values.expiry_date. Mark a row as expired when the date is in the past. Do not invent a verified badge — the verification field is private and never appears in the response.

Learning resources

Why

Showing a candidate's learning track needs more than a name: a cover image, a formatted overview, a downloadable syllabus, and a link to the technology it teaches. One collection can hold all four, and a reference field ties it back to Technologies so the two stay in sync.

Fields

Sample entries

The CSV carries only name, external_id, and summary. Image, file, and collection reference columns are rejected by the importer, so upload the cover and syllabus and pick the technology on each entry after the import finishes.

Connect it

1. Create the Learning resources collection in Settings → Collections and add the five fields above. Set technology to reference the Technologies collection with Single selection.
2. Import the CSV, then open each entry to upload its cover and syllabus and pick its technology.
3. Open Settings → Talent profile → Custom fields → Add field → Collection reference.
4. Label it Learning track, key learning_track, select the Learning resources collection, and choose Single.
5. Keep Show on public profile and Profile owner can edit on so candidates pick their own track.

What the API returns

An Image or File attribute is a single metadata object; an Image gallery attribute is an array of them. references is keyed by the reference field's key and always holds an array, even for a single selection.

Render it with the SDK

Ask the AI builder

On the talent profile, add a "Learning track" panel from the single objectReferences selection whose fieldKey is learning_track. Use the returned attributes.cover.url for the image, title and description for the header, attributes.overview as already-sanitised HTML, and attributes.syllabus.url for a download link labelled with attributes.syllabus.name. Show the linked technology from references.technology[0].name. Render nothing for any part the response omits.

Limits and tips

• A profile type supports up to 50 collection-reference fields, and a collection can hold its own fields plus references to other collections. One account can hold up to 100 collections.
• A Single field stores one entry. A Multiple field's ceiling is an operator-defined maximum, up to 100 entries, set with Maximum selections and editable later. One profile stores at most 500 collection selections in total and at most 100 repeatable detail rows per selection. A job form accepts up to 20 collection fields, and one job stores at most 500 selections across them.
• Rich text is sanitised on write and capped at 20,000 characters after unsupported markup is removed. Short text is capped at 200 characters and long text at 2,000.
• Image galleries hold up to 10 images, and any single upload is limited to 10 MB. CSV files are limited to 8 MB in the dashboard; the background import API accepts payloads up to 10 MB.
• Entry names are capped at 160 characters and external IDs at 200. Give every row an external ID so a re-import updates instead of duplicating.
• Archiving an entry keeps the selection stored on the profiles that already chose it, so an owner can save their profile without losing it, but the entry stops appearing in new choices, in resolved API responses, and in filters. An archived choice used as a filter returns invalid_filter.
• Collection keys and saved field types are immutable. Pick a key that describes the data rather than today's wording, because labels can change later and keys cannot.
• Import the text, number, date, select, and URL columns from CSV; add image, file, and reference values on each entry afterwards.
• Filters accept at most 10 clauses per array and 10 values per clause, and only public fields and active public entries can be filtered. Always send record IDs from board.profileFields.choices or board.jobs.collectionChoices, never display names.

See also

• Profile fields and collections
• Profile fields namespace
• Companies namespace
• Talent namespace
• Jobs namespace
• Candidate account namespace
• AI website builder