Profile fields and collections

Profile fields add structured information to company and talent profiles. Use a direct profile field for a value that belongs only to one profile, such as an accreditation status or membership number. Use a collection when many profiles should choose from the same managed set of entries, such as technologies, benefits, or certifications.

You configure both from Settings. Company profile and Talent profile contain the fields for each profile type. Collections contains the reusable entries those profiles can select.

Where fields appear

Profile fields and collections are a dashboard and API feature:

• The dashboard manages them. Definitions, collection entries, imports, and stored values all live in Settings and the profile editors.
• The public API and the Board SDK expose them: definitions, collection choices, and resolved values for public fields, so an AI-builder board or your own custom board can render them however it likes.
• Cavuno-hosted boards do not render custom profile fields or collections on company, talent, or job pages.
• Hosted posting forms do not show collection fields. Required collection fields apply to dashboard and API writes.

Before you begin

You need account access that can manage settings to define fields and collections. To use the operator API, create a server-side API key with the scopes named in the API reference. To use the Board SDK owner methods, sign the candidate or employer in and pass that board-user session to the client.

Add a profile field

1. Open Settings → Company profile or Settings → Talent profile.
2. In Custom fields, click Add field.
3. Enter a label and check the API key Cavuno derives from it.
4. Choose the field type and its settings.
5. Click Save field.

Adding a field opens a focused modal. Editing an existing field opens a drawer so you can keep the field list in view. A saved field's key and type are fixed. Choose a stable key that describes the data rather than its current display wording.

Company and talent profiles support these field types:

Select fields need at least one option. Option keys are the stored values, while labels are the wording people see. Number limits validate values entered later.

Order, show and require profile fields

Settings → Company profile and Settings → Talent profile each list every field of that form in one table: the built-in fields (such as website, logo and summary for companies, or headline, bio and skills for talent), your custom fields and your collection fields. The order of the table is the order of the form.

• Reorder: drag a row by its handle, or use the row menu's Move up and Move down.
• Show or hide: untick Shown to remove a field from the form. Stored values are kept. Unticking Shown also unticks Required.
• Require: tick Required to make the field mandatory. A hidden field cannot be required, and a field that cannot be required shows a disabled box with a tooltip.

A few built-in fields are locked, so both boxes stay ticked: the company name, which is the hiring organization on every job posting, and the talent name and email, which a profile needs to exist and be contacted. Hiding a company's logo or website is allowed, but Settings warns that it can reduce your visibility in Google for Jobs.

Boards built with the AI builder or the Board SDK read these forms from the public board context (forms.company and forms.talent on GET /v1/boards/{identifier}), in your order and with public field definitions included. Private fields never appear there. The operator API reads and replaces the layouts with GET and PUT /v1/settings/form-layouts.

Set visibility and editing access

Each field has two independent controls:

• Show on public profile controls whether the value is published through the public API and the Board SDK. Turn it off for operator or member information that should stay private.
• Profile owner can edit controls whether the candidate or an approved company member can change the value through the owner endpoints of the API and SDK.

This gives you four useful combinations. A public owner-editable field can be self-maintained and published. A public operator-managed field can show a verified value that only your team changes. A private owner-editable field lets the owner supply information without publishing it. A private operator-managed field stays internal.

Operators can view all configured values from the dashboard. On candidate profiles, the dashboard leaves owner-editable values to the candidate and lets the operator maintain operator-managed values. Company operators can maintain the company's configured values. An owner reaches their own values through the owner endpoints, which accept changes to owner-editable fields only. Public API and Board SDK responses only include fields marked public.

Create a collection

1. Open Settings → Collections.
2. Click Add collection.
3. Give the collection a name and stable API key.
4. Add any fields shared by every collection entry.
5. Save the collection, open it, and add entries.

Every entry includes a name; everything else is a field you add. Fields can contain plain or rich text, choices, numbers, dates, contact details, uploaded images and files, or references to another collection. For a Technologies collection, for example, each entry might contain the technology name, logo, website, and category. Updating that shared entry updates the common source data used by every profile that selected it.

To give entries a logo, add an Image field to the collection, then open that field's row menu in Collection settings and choose Use as logo. The row shows a Logo badge, and each entry's image in that field becomes its logo wherever the entry appears. Only one Image field can be the logo; choose Stop using as logo to clear it. Entries saved before logos became an Image field keep their stored logo URL, shown read-only in the entry editor, until the collection marks an Image field as its logo.

Archiving keeps a collection or entry available to existing data while removing it from normal new choices. You can include archived resources when reading them through the operator API.

Entry slugs

Every entry has a slug: a URL-safe identifier such as annual-leave, unique within its collection. Cavuno creates it from the entry name when the entry is added in the dashboard, through the API, or by a JSON or CSV import. Accents become plain letters, other characters become hyphens, and a name another entry already uses gets -2, -3 and so on. Renaming an entry keeps its slug, so links built from it keep working.

To change a slug, open the entry and edit Slug. It accepts up to 80 lowercase letters, numbers and single hyphens. The old slug stays reserved for that entry: no other entry in the collection can take it, but the same entry can switch back to it later.

Slugs appear as slug on collection records in the operator API, on company and talent selections, on job collection entries, and on choice lists. Send slug when updating a record to change it; a slug another entry uses or reserved returns a 400 error that names the slug field. Cavuno-hosted boards do not publish entry pages, so use slugs to build entry URLs in your own frontend.

Connect a collection to profiles

After creating a collection, return to Company profile or Talent profile and open Add field → Collection reference in the Custom fields table:

1. Click Add field.
2. Add its label and stable key, then select the collection.
3. Choose whether a profile can select one or multiple entries. When multiple entries are allowed, set Maximum selections — any whole number from 1 to 100. It defaults to 100, the highest the platform allows, and you can change it later.
4. Set public visibility and owner editing independently.
5. Add profile-specific details or repeatable details when needed.
6. Click Save field.

You can select one short-text or long-text collection attribute as the default description. Turn on Allow title and description changes when individual profiles should be able to replace the shared title or description. They can later restore the collection default.

For example, keep Annual leave as one shared Benefits entry with a default title and a description such as "Paid time away from work." A company can override the title with Flexible annual leave and describe its own policy without changing the collection entry other companies use. Add a Days per year detail to the profile selection when the allowance should also be stored as a typed value. Clearing either override restores the collection default.

For a Technologies collection, store each technology as one entry and upload its official logo to the collection's logo Image field. A selected technology resolves to an object with its recordId, title, optional description, logoUrl, shared attributes, and profile-specific details. A board built on the API or the SDK can render that resolved object directly, including the logo, without maintaining a second technology-to-logo map.

Details per selection stores one typed set of values for the selected entry. Repeatable details stores multiple typed rows beneath it. A Certifications collection could use repeatable details for several awards of the same certification, with an issuer and expiry date on each row.

When a collection allows multiple selections, the dashboard profile editor's Add button opens a searchable checklist. Select entries across searches, then choose Add entries to add the batch. The new rows appear immediately with their names and logos. Selection details are optional: use a row's edit action when that profile needs overrides, typed details, or repeatable rows. Canceling the picker leaves the current profile draft unchanged.

Format and organise collection fields

Use Rich text for formatted descriptions. Long text stays plain text. Rich text supports basic formatting and safe links, with a 20,000-character limit after unsupported markup is removed.

Add Image, Image gallery, or File fields for uploaded content. Galleries support up to 10 images, and individual files are limited to 10 MB. Field visibility applies to uploaded content as well as text.

A Collection reference field links an entry to entries in another collection. Choose single or multiple selection, and set Maximum selections (1 to 100) when multiple entries are allowed. Shared names update when the referenced entry changes; public output only includes public fields from active entries.

Add help text to explain what people should enter. Use the field ordering controls to arrange the entry form without changing stored answers.

Use collections on jobs

Open Settings → Job form → Custom fields → Add field → Collection reference. Choose a collection, whether posters can select one or multiple entries, and whether an answer is required. When multiple entries are allowed, Maximum selections sets how many a poster can choose — any whole number from 1 to 100, defaulting to 100. Existing fields keep the platform ceiling until you set a lower number, and the setting stays editable after the field is created.

Posters choose entries in the dashboard job form, and integrations send them with the job through the API. Cavuno-hosted posting forms do not show collection fields, so a required collection field is enforced on dashboard and API writes only. Job references use entry IDs, so changing an entry name keeps its associations intact.

As on profiles, you can pick one short-text, long-text or rich-text collection field as Default description, and turn on Allow title and description changes under What each job can change. With that switch on, each selected entry in the dashboard job form has an edit button. It opens a Title and Description editor for that job only; leave a box empty to keep the collection default, or choose Restore defaults to clear both. Titles can be up to 160 characters and descriptions up to 2,000. The shared entry does not change, so other jobs keep its wording.

Job wording is plain text. When the default description is a rich text field, the API returns the job's description as HTML paragraphs with the wording escaped.

A job's wording belongs to its selection. Removing the entry from the job removes its wording, editing the job keeps it, and duplicating the job copies it. Turning the switch off hides stored wording on job responses, and the next dashboard save of that job removes it.

Through the API, send collectionOverrides with the job: one { fieldKey, recordId, title, description } item per selected entry that has its own wording. The operator job endpoints and the employer company job endpoints both accept it. The list replaces the job's stored wording: on an update, leave it out to keep what is stored or send [] to restore every default. Wording for an entry the job does not select, or on a field that does not allow changes, returns a 400 jobs_constraint_violation error naming the field. Each job collection entry in a response carries title and description, already resolved to the job's wording or the collection default, plus titleOverride and descriptionOverride, which are null when the job uses the default.

Import collection entries from CSV

Open a collection, open its actions menu, and choose Import CSV. Upload or drop a CSV file, match columns to the entry name, external ID, legacy logo URL, and collection fields, then review the mapped data before starting the import. Images, including logos, cannot be imported; upload them in the entry editor.

The dashboard importer has these rules:

• The file must be 8 MB or smaller and contain a header row and at least one data row.
• Every column needs a unique header, and every row must have the same number of columns.
• Name is required and can be up to 160 characters.
• Logo URLs must use HTTP or HTTPS.
• Boolean values accept true, false, 1, 0, yes, or no.
• Multi-select values use | between options.
• The review shows the first 20 entries before the import starts.

The import runs in the background, so you can leave the progress page while it continues. Entries with an external ID matching an existing entry are updated and restored if archived. Other rows create new entries. An update replaces the entry's imported values: blank or unmapped fields are cleared. Use a small representative file first when you need to confirm mappings.

Use the operator API

The operator API exposes scalar profile definitions and values, plus collections and their entries. The API reference calls a collection a catalog type and an entry a catalog record. Create an API key in Settings → Developer → API keys while signed in as an account member with the permissions required by the endpoint.

Profile definition endpoints are:

The PUT request replaces the complete ordered definition array. Reading needs settings.read; replacing needs settings.manage.

Read or additively update scalar values with:

These operator reads include private definitions and values. A patch preserves omitted keys. Send null, a blank string, or an empty array to clear one value; false and 0 remain real values.

Collection endpoints use /v1/custom-object-types for collection definitions, /v1/custom-object-types/{typeId}/records for entries, and /v1/custom-object-records/{recordId} for one entry. The synchronous import endpoint accepts up to 500 records atomically:

For example, create a Technologies collection with an optional website field:

Send that body to POST /v1/custom-object-types, then create an entry at POST /v1/custom-object-types/{typeId}/records with its name, optional externalId, and a typed values object:

To mark a logo, add an image definition and send its key as logoFieldKey when you create or update the collection; null clears it, and removing that definition clears it too. Resolved selections, job collection entries, and choice rows return the entry's image in that field as logoUrl. The record-level logoUrl input is deprecated: it still stores a legacy logo URL, which is returned when the entry has no logo image.

Configure the collection field that connects those entries to profiles in Company profile or Talent profile. Operator integrations read and replace selections through GET and PUT /v1/candidates/{id}/object-references or /v1/companies/{id}/object-references.

For a larger JSON payload, start a background operation at:

The background request is limited to 10 MB. Follow the returned operation through the operations API. Its terminal result reports total, created, updated, and failed rows with a capped set of row errors. Both import forms update and restore an entry when its externalId already exists within that collection; otherwise they create a new entry.

Collection keys and saved field types are immutable. On record updates, omitted properties are preserved, null clears externalId or the deprecated logoUrl, and a supplied values object replaces all stored entry values.

Use the generated API reference as the exact request and response contract.

Render scalar fields with the Board SDK

The Board SDK exposes the authenticated owner's scalar profile-field definitions and raw values. It does not decide which controls, layout, or copy your custom board should use.

For a candidate profile:

For a company where the signed-in user has approved membership:

Each read returns definitions and values. Use each definition's key, label, type, options, limits, visibility, and owner-editing flag to build your interface, and keep the stored value in its returned type. Updates are additive and only owner-editable keys change; omitted and non-editable keys are preserved.

See SDK fundamentals for authentication and client setup, and SDK reference for shared request behavior. Operator API keys belong on the server and are not Board SDK credentials.

Read and update collection selections with the SDK

Use board.me.profile.retrieveObjectReferences() for the signed-in candidate, or board.me.companies.retrieveObjectReferences('acme') for an approved company member. The response includes definitions and resolved selections, including shared titles, descriptions, attributes, and profile-specific details.

Use updateObjectReferences({ selections }) on the candidate namespace, or updateObjectReferences('acme', { selections }) on the company namespace. Send each selected record's fieldKey and recordId, with optional values, entries, titleOverride, and descriptionOverride. Repeatable entries need a stable key beginning with a letter, such as entry_123. Keep that key when editing the same entry. Omitted editable selections are removed; omitted read-only selections are preserved.

Build the replacement array from the current editable selections when you mean to retain them. The returned title, description, and logoUrl are already resolved for display; the optional override fields tell you when the profile replaced a collection default.

Filter search results

Job, company, and talent search accept customFields, an array of { key, values } clauses. Company and talent search also accept objectReferences, an array of { key, recordIds } clauses. Clauses are combined with AND; values within one clause are alternatives. Use stored option keys for select fields and preserve the original number or boolean type, including 0 and false.

Build public company and talent filter controls from board.profileFields.retrieve('company') or retrieve('candidate'). Each response contains the public scalar definitions and public collection-reference definitions for that entity. Load an active collection's labels, IDs, and optional logos with board.profileFields.choices(entity, fieldKey, { search, cursor, limit }). Collection administration and imports remain server-only operator API operations; they are not Board SDK methods.

Only public fields and active public collection selections can be used. Unknown, private, invalid, and archived filter choices return invalid_filter. Each filter array accepts up to 10 clauses, with up to 10 values per clause. Filters apply before counting and pagination. The SDK encodes talent filter arrays in query parameters for you.

Talent custom filters compose with skill, job search status, language, and relocation filters. Combining them with sort: 'newest' is currently unsupported and returns invalid_filter.

Verify the setup

After saving a definition, add a value or collection selection to one test profile and reload its editor. Read that profile back through the public API or the SDK, check the public value is there, and confirm the private value is absent. If the field is intended for discovery, search with its stored key and value or record ID and confirm the matching profile appears. For imports, wait for the operation to finish and compare its created, updated, and failed totals with the source file.

If a filter returns invalid_filter, confirm that the field and selected collection entry are active and public, and that the request uses stored keys or record IDs rather than display labels. If an import reports row errors, correct those rows and retry; a matching external ID updates the existing entry instead of creating a duplicate.

Related guides

• Collection examples: worked benefits, technologies, certifications and learning-resource collections with SDK rendering and AI builder prompts
• Edit a company profile
• Job seeker profiles
• Company directory
• Import and export