Preference profiles

Contact Ferretly before creating, updating or deleting profiles

The API-client setting allowPreferenceProfileUpdate must be enabled by Ferretly before you can use the POST, PUT or DELETE preference-profile endpoints. Contact Ferretly Integrations to enable it for your client. Reading profiles does not grant permission to modify them.

Operations

Use preference profiles to configure screening behavior for your organization.

Method	Path	Purpose
GET	/api/PreferenceProfiles/behavior-categories	Default behavior categories
GET	/api/PreferenceProfiles	Organization profile summaries
POST	/api/PreferenceProfiles	Create an organization-wide profile
GET	/api/PreferenceProfiles/{id}	Read a full profile
PUT	/api/PreferenceProfiles/{id}	Update a profile
DELETE	/api/PreferenceProfiles/{id}	Soft-delete a profile

Permissions and validation

Create, update and delete require allowPreferenceProfileUpdate on the API client. They can also be disabled by server configuration. A 403 can therefore indicate an organization permission, ownership, or feature gate; inspect the operation’s documented response.

To delete a profile, it must belong to your organization and must not be the organization-wide default.

Ferretly validates behavior-category IDs, post types, disabled platforms, profile names, and notification settings. The organization-wide default profile cannot be deleted. Updates can also reject a default-profile rename, subscriber-specific profile, or mismatched route/body ID.

Request and response models differ

POST and PUT accept PreferenceProfileUpsert. Its JSON property names include:

id, profile_name, behavior_categories, key_words, general_settings, and disabled_platforms.

The list endpoint returns PreferenceProfile summaries. Single-profile reads and writes return OrganizationPreferencesProfile.

Do not send a GET response back unchanged as a PUT body; map it to the request model and preserve the settings you intend to keep.

Disable selected platforms

disabled_platforms is an exclusion list in the write model:

• Omit it to preserve the stored selection during an update.
• Send [] to enable all supported platforms.
• Send a platform list to replace the exclusions.

Supported values are Facebook, Instagram, Twitter, LinkedIn, TikTok, Reddit, Pinterest, and YouTube. Handles on excluded platforms are not scraped or automatically attached during screening.

When updating other fields, send the settings you want to retain using the complete request model.

Select a profile at subject creation

Set preferencesProfile to an existing profile name or UUID:

{
  "subjectData": { "name": "Example Candidate" },
  "preferencesProfile": "YOUR_EXISTING_PROFILE",
  "assignToFerretlyAnalyst": false,
  "isDebug": true
}

Replace YOUR_EXISTING_PROFILE with a profile in your organization. See debug mode guidance before testing.

New subjects start with the selected owner’s default profile for new subjects. It uses a matching name or UUID only when the profile belongs to the organization. An unrecognized selection can fall back to the default; inspect the returned subject’s profile rather than assuming an invalid name was rejected.

See the API reference for complete request schemas and documented error responses.