Create a preference profile

POST /api/PreferenceProfiles

Preference profile creation requires the ‘AllowPreferenceProfileUpdate’ setting to be enabled for your organization by Ferretly.

Authentication

Send your private API key in the X-Api-Key header. Keep it on your server.

This request can change account configuration or stored data. Review the example values before running it.

Request example

Examples use illustrative values. Set FERRETLY_API_KEY in your server environment for JavaScript, Python, and C#. Replace sample IDs, URLs, and profile values before use.

curl --fail -sS -X POST "https://api.ferretly.com/api/PreferenceProfiles" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "profile_name": "Integration example",
  "behavior_categories": [],
  "general_settings": {
    "email_me": false,
    "postTypesToAnalyze": [
      "Post",
      "Reply",
      "Like",
      "Repost"
    ]
  }
}'

const response = await fetch("https://api.ferretly.com/api/PreferenceProfiles", {
  "method": "POST",
  "headers": {
    "X-Api-Key": process.env.FERRETLY_API_KEY,
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "profile_name": "Integration example",
  "behavior_categories": [],
  "general_settings": {
    "email_me": false,
    "postTypesToAnalyze": [
      "Post",
      "Reply",
      "Like",
      "Repost"
    ]
  }
})
});
if (!response.ok) throw new Error("HTTP " + response.status);
console.log(await response.json());

import os
import requests
import json

response = requests.request(
    "POST",
    "https://api.ferretly.com/api/PreferenceProfiles",
    headers={"X-Api-Key":os.environ["FERRETLY_API_KEY"],"Accept":"application/json","Content-Type":"application/json"},
    json=json.loads("{\"profile_name\":\"Integration example\",\"behavior_categories\":[],\"general_settings\":{\"email_me\":false,\"postTypesToAnalyze\":[\"Post\",\"Reply\",\"Like\",\"Repost\"]}}"),
    timeout=30,
)
response.raise_for_status()
print(response.json())

using System;
using System.IO;
using System.Net.Http;
using System.Text;

using var http = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("POST"), "https://api.ferretly.com/api/PreferenceProfiles");
request.Headers.Add("X-Api-Key", Environment.GetEnvironmentVariable("FERRETLY_API_KEY"));
request.Headers.Accept.ParseAdd("application/json");
request.Content = new StringContent("{\"profile_name\":\"Integration example\",\"behavior_categories\":[],\"general_settings\":{\"email_me\":false,\"postTypesToAnalyze\":[\"Post\",\"Reply\",\"Like\",\"Repost\"]}}", Encoding.UTF8, "application/json");
using var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

The example profile name and settings are illustrative. Use the behavior-category IDs returned by the category endpoint and map the settings you intend to retain into the write model. A PUT is not a partial patch. Preference profiles.

Request body

Use application/json for JSON examples. The published operation also advertises these content types.

application/json-patch+json: PreferenceProfileUpsert
application/json: PreferenceProfileUpsert
text/json: PreferenceProfileUpsert
application/*+json: PreferenceProfileUpsert

Property	Type	Description
`id`	string (uuid)
`profile_name`	string	Gets or sets the name of the preference profile.
`behavior_categories`	array of PreferenceProfileBehaviorCategory	Gets or sets the list of behavior categories associated with a preference profile. Nullable.
`key_words`	KeyWords
`general_settings`	GeneralSettings
`disabled_platforms`	array of string	Gets or sets the social media platforms this profile turns off. Omit this field to leave the stored selection unchanged, send an empty list to turn every platform back on, or send a list of platforms to replace the selection. Nullable.

behavior_categories properties

Property	Type	Description
`id`	integer (int32)	Gets or sets the identifier for the behavior category in the preference profile. This property uniquely represents a behavior category within the context of the preference profile functionality.
`name`	string	Gets or sets the name of the behavior category associated with the preference profile. This property represents a descriptive label or title for the behavior category, enabling better context and readability in the preference profile configuration. Nullable.
`active`	boolean	Gets or sets a value indicating whether the behavior category is active. This property determines if the behavior category is considered enabled within the context of the preference profile functionality.
`behaviorType`	RiskType

key_words properties

Property	Type	Description
`is_active`	boolean
`key_words`	array of Keyword	Nullable.

general_settings properties

Property	Type	Description
`email_me`	boolean	Indicates whether to send background check status change emails to the user specified in NotificationEmailAddress
`notificationEmailAddress`	string	Nullable.
`email_subject_owner_on_completion`	boolean	When true, causes emails to be sent only upon mark redressed for organizations with Analyst Assistance, or upon run complete w/o Analyst Assistance.
`is_flagged`	boolean
`is_negative`	boolean
`is_positive`	boolean
`hide_logos`	boolean
`includeHelpPagesOnBackgroundReport`	boolean
`includeHyperlinksInReports`	boolean
`include_web_news_posts`	boolean	If true, a news/web search will be performed for the subject, and results will be added as new posts
`minimum_web_post_confidence_level`	string	String representation of MinimumWebPostConfidenceLevel, because of inconsistency in the way enums are serialized in the API Nullable.
`include_fcra`	boolean	Boolean to indicate whether FCRA warnings and disclaimers are shown, and to control number of years of posts to fetch
`isFCRAYearsOverriden`	boolean	When set to true, allows for AlternativeNumberOfYearsForPosts to specify number of years of posts to fetch
`alternativeNumberOfYearsForPosts`	integer (int32)	If IsFCRAYearsOverriden is true, number of years of posts to retrieve Nullable.
`anonymizeProfilePictureInReports`	boolean
`includePostInsightsInReports`	boolean
`basicInsightsIsOnePage`	boolean
`report_background_color`	string	Background color for the report. Nullable.
`hideSentimentOnReports`	boolean	If true then don’t display sentiment icon on posts pages in reports
`useAlternateDisclaimerText`	boolean	A boolean to indicate whether the organization’s “Alternate Disclaimer Text” should be used in the report
`showZeroScoreWhenNoHandles`	boolean	“Show Score as 0 when no handles”
`excludeHandleBiosOnCoverPage`	boolean	“Exclude Handle Bio’s on cover page”
`excludeScoreOnPostsInsights`	boolean	“Exclude score on post insights”
`isPrinterFriendlyReport`	boolean	Boolean to indicate that the report style should be “printer friendly”
`reportAnalyticsSections`	ReportAnalyticsSections
`includeAbstract`	boolean
`excludeFlaggedPostSummary`	boolean
`postTypesToAnalyze`	array of string	A list of post types that will be analyzed in the report. This list is exclusionary: if it is not empty, then only the post types in this list will be analyzed. If the list is empty, all post types will be analyzed. Nullable.
`showBehaviorIconsInReports`	boolean	Gets or sets a value indicating whether to show behavior icons on reports.
`redactNudeImagesInReports`	boolean	Gets or sets a value indicating whether to redact nude images in reports.
`group_posts_by`	string	String representation of GroupPostsBy, because of inconsistency in the way enums are serialized in the API Nullable.
`report_language_iso_code`	string	Gets or sets a value indicating report language ISO code Nullable.
`includePostTagsInReports`	boolean	Boolean to indicate whether to include each post’s Tags in reports
`hideSubjectProvidedPropertiesInReports`	boolean	Boolean to indicate whether to hide section with subject provided properties in reports.
`disableAutomaticAgenticSearch`	boolean	If true, prevents automatic agentic AI profile search from being initiated when a subject is assigned to an analyst or when a background check is initiated.

Responses

200

Success

text/plain: OrganizationPreferencesProfile
application/json: OrganizationPreferencesProfile
text/json: OrganizationPreferencesProfile

400

The request body is null; one or more behavior categories are not valid; the profile name is already in use; ‘Email me’ is enabled but no notification address is provided; or the notification email address is invalid.

401

The subscriber or organization identifier is missing from the request credentials.

403

The preference profile creation endpoint is disabled by configuration, or the organization is not allowed to create preference profiles.

404

No subscriber was found for the provided identifiers.

Response example

Illustrative, shortened HTTP 200 response. Optional fields can be absent or null.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "profile_name": "Integration example",
  "isOrganizationDefaultProfile": false
}

Response properties

Property	Type	Description
`id`	string (uuid)	The unique identifier for this profile
`profile_name`	string	Nullable.
`organizationId`	string (uuid)	The organization to which this profile belongs
`organizationName`	string	The name of the organization Nullable.
`isOrganizationDefaultProfile`	boolean	Whether or not this profile is the organization default Read-only response field.
`subscriberId`	string (uuid)	If not null, this is a private profile Nullable.
`isPrivateProfile`	boolean	Read-only response field.
`isActive`	boolean	Support soft deletes of profiles
`risk_categories`	array of OrganizationRiskCategory	Nullable.
`key_words`	KeyWords
`general_settings`	GeneralSettings
`disabledPlatforms`	array of string	A list of social media platforms this profile has turned off. This list is exclusionary: if it is not empty, then handles on those platforms are not scraped and profiles found there are not attached automatically. If the list is empty, every platform applies. Nullable.
`lastEdited`	string (date-time)
`lastEditedBy`	string (uuid)	The ID of the Subscriber who last edited this profile. Null when the profile was last edited via the external API. Nullable.
`lastEditedByName`	string	The display name of the person or system that last edited this profile. Populated at write time. For human edits this is “{FirstName} {LastName}”; for external API edits this is the API client’s Owner name. Nullable.

risk_categories properties

Property	Type	Description
`id`	integer (int32)
`name`	string	Nullable.
`active`	boolean
`sort_order`	integer (int32)
`risk_type`	RiskType