Create persona set

posthttps://api.faraday.ai/v1/persona_sets

Invoke the build of a new persona set for a given cohort

Authentication

Bearer Authentication

Provide your API key in the Authorization header. You can find your API key in the Settings page of the dashboard.

Authorization: Bearer YOUR_TOKEN

Body

Configuration parameters for the new persona model

The dimensions the clustering system should consider when discovering the personas in a persona set.

By default, Faraday will consider a fixed set of broadly effective dimensions when discovering you...

Properties of object

Pin the FIG attribute release used for clustering: only attribute data observed on or before this date is considered. If not set, the freshest available data is used.

Only available on accounts with ...

attributesarray[string enum]

Faraday-provided attributes to consider for clustering, drawn from the allowed set of broadly effective attributes.

Only available on accounts with an identity graph feature store set.

Allowed values: fig/total_purchase_count_observed_quintile, fig/total_amount_spent_on_purchases_quintile, fig/age, fig/collectibles_art_antiques_interest, fig/general_book_reading_interest, fig/charitable_donation_interest, fig/nutrition_interest, fig/household_education, fig/automated_valuation_model, fig/tax_assessed_property_value, fig/gardening_interest, fig/gender, fig/fitness_interest, fig/home_ownership_status, fig/household_income, fig/household_size, fig/length_of_residence, fig/interest_in_sports, fig/property_living_area, fig/marital_status, fig/individual_marital_status, fig/music_interest, fig/net_worth, fig/current_installment_loan_to_value, fig/pet_interest, fig/purchased_via_internet, fig/shopping_styles, fig/general_travel_interest, fig/travel_interest, fig/housing_density, fig/credit_score_proxy, fig/marketing_value_overall, fig/home_year_built
streamsdictionary[string, array]

Event stream properties to consider for clustering, keyed by the name of an event stream used by this persona set's cohort. Each value is the list of property names on that stream to consider.

If you...

Additional properties: allowed (values are array)
traitsarray[string]

First-party traits defined on your account to consider for clustering.

On accounts without an identity graph feature store set, Faraday-provided FIG traits may also be included here by prefixing the ...

cohort_idstring<uuid>required

The cohort to organize into personas. Personas are built from cohort members matched at the individual level.

Example: "5bf9aa70-7bf1-4ef1-a131-8c84441be231"
explorebooleandeprecated

Deprecated. This field has no effect. Faraday keeps the value only for backward compatibility.

Example: false
Default: false
modeling_attributesarray[string enum]deprecated

Deprecated. Use clustering_dimensions instead.

Specify Faraday provided attributes to use in modeling. Only available to accounts with an identity graph feature store set.

Mutually exclusive with ...

Allowed values: fig/total_purchase_count_observed_quintile, fig/total_amount_spent_on_purchases_quintile, fig/age, fig/collectibles_art_antiques_interest, fig/general_book_reading_interest, fig/charitable_donation_interest, fig/nutrition_interest, fig/household_education, fig/automated_valuation_model, fig/tax_assessed_property_value, fig/gardening_interest, fig/gender, fig/fitness_interest, fig/home_ownership_status, fig/household_income, fig/household_size, fig/length_of_residence, fig/interest_in_sports, fig/property_living_area, fig/marital_status, fig/individual_marital_status, fig/music_interest, fig/net_worth, fig/current_installment_loan_to_value, fig/pet_interest, fig/purchased_via_internet, fig/shopping_styles, fig/general_travel_interest, fig/travel_interest, fig/housing_density, fig/credit_score_proxy, fig/marketing_value_overall, fig/home_year_built

Deprecated. Use clustering_dimensions.attribute_max_observation_date instead.

The maximum date for FIG attribute observations used in modeling fields. When set, only attribute data observed on or b...

modeling_fieldsarray[string enum]deprecated

Deprecated. Use clustering_dimensions instead.

Specify Faraday provided traits to use in modeling.

Only valid on accounts that do not have an identity graph feature store set, which must use model...

Allowed values: fig/actvty_num_purchase_quintile, fig/actvty_ttl_dollars_quintile, fig/age, fig/antiques, fig/books_magazines, fig/charitable_donations, fig/dieting, fig/education, fig/favm, fig/frequent_remodeler, fig/gardener, fig/gender, fig/health_conscious, fig/homeowner_status, fig/household_income, fig/household_income_v2, fig/household_size, fig/length_of_residence, fig/length_of_residence_v2, fig/life_sports_sports_all, fig/living_area, fig/marital_status, fig/music, fig/net_worth, fig/percent_equity, fig/pet_any, fig/purch_chan_internet, fig/shopping_styles, fig/travel, fig/housing_density, fig/value_score_all, fig/year_built
namestringrequired

Human-readable label for this persona set.

Example: "Customers personas"
Match pattern: ^(?!\s*$).+
Maximum characters: 64

Specify the exact number of clusters (i.e. personas) there should be in the persona set.

By default, the optimal value for this parameter is determined automatically.

Setting this requires external ...

previewboolean

A persona set in preview mode will not build until preview is turned off.

Example: true

Responses

201The newly created persona set (still building)
activeboolean

Is the related cohort using this as the primary persona set?

archived_atstring<date-time>

If not null, this resource will no longer receive updates, but will still be visable.

The dimensions the clustering system should consider when discovering the personas in a persona set.

By default, Faraday will consider a fixed set of broadly effective dimensions when discovering you...

Properties of object

Pin the FIG attribute release used for clustering: only attribute data observed on or before this date is considered. If not set, the freshest available data is used.

Only available on accounts with ...

attributesarray[string enum]

Faraday-provided attributes to consider for clustering, drawn from the allowed set of broadly effective attributes.

Only available on accounts with an identity graph feature store set.

Allowed values: fig/total_purchase_count_observed_quintile, fig/total_amount_spent_on_purchases_quintile, fig/age, fig/collectibles_art_antiques_interest, fig/general_book_reading_interest, fig/charitable_donation_interest, fig/nutrition_interest, fig/household_education, fig/automated_valuation_model, fig/tax_assessed_property_value, fig/gardening_interest, fig/gender, fig/fitness_interest, fig/home_ownership_status, fig/household_income, fig/household_size, fig/length_of_residence, fig/interest_in_sports, fig/property_living_area, fig/marital_status, fig/individual_marital_status, fig/music_interest, fig/net_worth, fig/current_installment_loan_to_value, fig/pet_interest, fig/purchased_via_internet, fig/shopping_styles, fig/general_travel_interest, fig/travel_interest, fig/housing_density, fig/credit_score_proxy, fig/marketing_value_overall, fig/home_year_built
streamsdictionary[string, array]

Event stream properties to consider for clustering, keyed by the name of an event stream used by this persona set's cohort. Each value is the list of property names on that stream to consider.

If you...

Additional properties: allowed (values are array)
traitsarray[string]

First-party traits defined on your account to consider for clustering.

On accounts without an identity graph feature store set, Faraday-provided FIG traits may also be included here by prefixing the ...

cohort_idstring<uuid>required

The cohort to organize into personas. Personas are built from cohort members matched at the individual level.

Example: "5bf9aa70-7bf1-4ef1-a131-8c84441be231"
created_atstring<date-time>required

When this resource was created. It says nothing about builds; to check status, see Status and timestamps.

explorebooleandeprecated

Deprecated. This field has no effect. Faraday keeps the value only for backward compatibility.

Example: false
Default: false
idstring<uuid>required

A unique ID for this resource.

Example: "4b3f42dd-b6c3-4f0f-ac18-9e6e47321f83"
last_read_input_atstring<date-time>

When the latest finished build started reading this resource's configuration and inputs; omitted until the first build finishes. Once this is at or after last_updated_config_at, a build with the cur...

last_updated_config_atstring<date-time>

When Faraday registered the latest change to this resource's configuration, or the latest force_update. A create, update or force_update response carries the value then on record (an update that c...

last_updated_output_atstring<date-time>

When a build last changed this resource's output. A build that finishes with nothing new to write does not move it.

modeling_attributesarray[string enum]deprecated

Deprecated. Use clustering_dimensions instead.

Specify Faraday provided attributes to use in modeling. Only available to accounts with an identity graph feature store set.

Mutually exclusive with ...

Allowed values: fig/total_purchase_count_observed_quintile, fig/total_amount_spent_on_purchases_quintile, fig/age, fig/collectibles_art_antiques_interest, fig/general_book_reading_interest, fig/charitable_donation_interest, fig/nutrition_interest, fig/household_education, fig/automated_valuation_model, fig/tax_assessed_property_value, fig/gardening_interest, fig/gender, fig/fitness_interest, fig/home_ownership_status, fig/household_income, fig/household_size, fig/length_of_residence, fig/interest_in_sports, fig/property_living_area, fig/marital_status, fig/individual_marital_status, fig/music_interest, fig/net_worth, fig/current_installment_loan_to_value, fig/pet_interest, fig/purchased_via_internet, fig/shopping_styles, fig/general_travel_interest, fig/travel_interest, fig/housing_density, fig/credit_score_proxy, fig/marketing_value_overall, fig/home_year_built

Deprecated. Use clustering_dimensions.attribute_max_observation_date instead.

The maximum date for FIG attribute observations used in modeling fields. When set, only attribute data observed on or b...

modeling_fieldsarray[string enum]deprecated

Deprecated. Use clustering_dimensions instead.

Specify Faraday provided traits to use in modeling.

Only valid on accounts that do not have an identity graph feature store set, which must use model...

Allowed values: fig/actvty_num_purchase_quintile, fig/actvty_ttl_dollars_quintile, fig/age, fig/antiques, fig/books_magazines, fig/charitable_donations, fig/dieting, fig/education, fig/favm, fig/frequent_remodeler, fig/gardener, fig/gender, fig/health_conscious, fig/homeowner_status, fig/household_income, fig/household_income_v2, fig/household_size, fig/length_of_residence, fig/length_of_residence_v2, fig/life_sports_sports_all, fig/living_area, fig/marital_status, fig/music, fig/net_worth, fig/percent_equity, fig/pet_any, fig/purch_chan_internet, fig/shopping_styles, fig/travel, fig/housing_density, fig/value_score_all, fig/year_built
namestringrequired

Human-readable label for this persona set.

Example: "Customers personas"
Match pattern: ^(?!\s*$).+
Maximum characters: 64

Specify the exact number of clusters (i.e. personas) there should be in the persona set.

By default, the optimal value for this parameter is determined automatically.

Setting this requires external ...

personasarray[object]

The personas that belong to this persona set

Items of array[object]
avatarstringdeprecated

Deprecated: Value will be null until the key is eventually removed or replaced. Previously, an image used to represent this persona (only available if demographics (age and gender) are included in the model)

Example: "https://app.faraday.ai/images/persona_stereotypes/face-5.jpg"
Match pattern: ^https://app.faraday.ai/images/persona_stereotypes/[A-Za-z0-9_][-A-Za-z0-9_ ]*.jpg$
detailsobject

Statistics about the members of this persona.

Additional properties: not allowed
Properties of object
binsobjectdeprecated

Deprecated: Use /persona_sets/{persona_set_id}/analysis/dimensions instead.

How much the members of the persona differ from an average member. This is represented as a histogram. For example, i...

Example: "{\n \"age\": [\n {\n \"max\": 20,\n \"min\": 0,\n \"count\": 0,\n \"percent\": 0.0\n },\n //...\n {\n \"max\": 30,\n \"min\": 20,\n \"count\": 6,\n \"percent\": 0.0035608308605341245\n },\n //...\n {\n \"max\": null,\n \"min\": 90,\n \"count\": 0,\n \"percent\": 0.0\n }\n ],\n \"gender\": [\n {\n \"count\": 1396,\n \"value\": \"Female\",\n \"percent\": 0.828486646884273\n },\n {\n \"count\": 289,\n \"value\": \"Male\",\n \"percent\": 0.171513353115727\n }\n ]\n //...\n}\n"
centerobject

The average traits of a member of this persona. A person does not need to match these traits exactly to be a member of the persona.

Example: "{\n \"age\": 38.98716,\n \"gender\": \"Female\",\n \"household_size\": 6.61248,\n \"household_income\": 148072.78481\n}\n"
idstring<uuid>required
Example: "5cc63c04-f451-43e4-98ce-0e755db8f8e6"

The number of individuals in this persona among members of the cohort used to generate the persona set who are matched at the individual level. Members matched only at the address level aren't used to build personas.

Example: 1000

Interpretation data for this persona

Properties of object

Marketing strategems for this persona

summarystring

A summary interpretation of this persona

namestringrequired

A human-readable label for this persona.

Example: "Cluster 0"
Match pattern: ^(?!\s*$).+
Maximum characters: 64
previewboolean

A persona set in preview mode will not build until preview is turned off.

Example: true
resource_typestringrequired

The type of this resource.

Example: "persona_sets"
statusstringrequired

The state of this resource's latest build. Until last_read_input_at is at or after last_updated_config_at, no build with the current configuration has finished (starting or running means one i...

Example: "ready"
Allowed values: new, starting, running, ready, error
status_changed_atstring<date-time>

When the status of this resource was last updated.

If this resource has status == "error", this will contain an error message.

What Faraday is waiting for before it builds a resource with status == "error" again. user: a configuration change to this resource or a force_update. support: Faraday support, and `force_upda...

Allowed values: user, support
updated_atstring<date-time>required

When this resource was last changed, by an edit or by Faraday while building it. Don't use it to check status; use last_updated_config_at and last_read_input_at as Status and timestamps explains.

400The request was invalid.
errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

  • BAD_REQUEST: The request could not be validated.
  • FORBIDDEN: You do not have permission to access the specified resour...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, INVALID_API_KEY, ACCOUNT_SUSPENDED, ACCOUNT_DELETED, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDED
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

A suggestion for fixing this error.

401No API key was supplied.
errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

  • BAD_REQUEST: The request could not be validated.
  • FORBIDDEN: You do not have permission to access the specified resour...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, INVALID_API_KEY, ACCOUNT_SUSPENDED, ACCOUNT_DELETED, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDED
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

A suggestion for fixing this error.

403Access to this resource was forbidden.
errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

  • BAD_REQUEST: The request could not be validated.
  • FORBIDDEN: You do not have permission to access the specified resour...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, INVALID_API_KEY, ACCOUNT_SUSPENDED, ACCOUNT_DELETED, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDED
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

A suggestion for fixing this error.

404The requested resource ID was not found.
errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

  • BAD_REQUEST: The request could not be validated.
  • FORBIDDEN: You do not have permission to access the specified resour...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, INVALID_API_KEY, ACCOUNT_SUSPENDED, ACCOUNT_DELETED, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDED
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

A suggestion for fixing this error.

500An internal server error occurred.
errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

  • BAD_REQUEST: The request could not be validated.
  • FORBIDDEN: You do not have permission to access the specified resour...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, INVALID_API_KEY, ACCOUNT_SUSPENDED, ACCOUNT_DELETED, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDED
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

A suggestion for fixing this error.

Tags

persona_sets