Ask users about themselves

A trait is a question your organization asks a user about themselves, such as the industry they work in, stored on their record. You declare each trait once, for all of your sites, in Identity › Audience › Traits. Users answer at sign-up and from a preferences form. Your rules and derivations then read the answers; see Profile.

Everyone in your organization can view traits. Declaring and changing them needs the Owner or Admin role.

When a change takes effect

A trait change reaches sign-up and preferences forms at once, with no deploy: GET /v1/id/traits and the sign-up fields in GET /v1/id/config read your current traits, and EdgeKit checks answers against them. Their answers are cached for up to 5 minutes, so a new question can take that long to appear. What your derivations read from a trait changes only after your next deploy. A deploy never undoes a trait change.

Declare a trait

1. In Identity › Audience › Traits, select Declare a trait.
2. Enter a Name: lowercase letters, digits and underscores, starting with a letter, such as job_industry. It is the key on every user’s record, and a derivation reads it as user.traits.job_industry.
3. Enter a Label, up to 200 characters. It is what your form shows beside the field.
4. Pick a Type:
   • Text: free text, up to 4096 characters.
   • Whole number or Number.
   • Yes / no.
   • List: one of a set of values you author on the trait’s own screen.
5. Turn on Allow more than one value if the user may give several, up to 100 per answer.
6. Turn on Required at sign-up if sign-up must not complete without an answer.
7. Pick who it is Written by:
   • The user: asked at sign-up, editable by the user, and read as something the user typed about themselves.
   • Your staff: never offered on a form and never writable by the user.
8. Select Declare.

Name, type and who writes it are fixed once declared. Label, Allow more than one value, Required at sign-up and a list trait’s default value can be changed on the trait’s screen. Your organization can declare up to 128 traits.

Required traits and magic links

A trait cannot be marked required while magic link is offered on any of your sites. A magic link creates the user with no traits, so a required question there would be asked of nobody. The refusal names the sites.

A required trait is checked on a sign-up request that carries userTraits. A sign-up with no userTraits still completes, so your sign-up form must ask the question. See Sign in with an emailed code.

Author a list trait’s values

Open the trait from Identity › Audience › Traits and go to Values.

1. Select Add value and enter a Label, up to 200 characters.
2. Optionally enter an External ID, up to 200 characters: your own key for the value, such as the one a data platform or an import joins on. It is published on GET /v1/id/traits, so leave it empty if it must stay private.

Each value gets an id, and a user’s record stores that id, not the label. You can reword a label at any time without changing any answer. A trait offers at most 512 values.

• Suppress a value to stop offering it. Users who chose it keep it on their record. Pick the trait’s Default value to have your derivations read that value instead for them; the default is never written to anyone’s record.
• Offer again brings a suppressed value back.
• Delete removes a value outright. Suppress it instead unless nobody has ever chosen it.

Stop collecting a trait

• Suppress stops asking the question: GET /v1/id/traits and GET /v1/id/config stop listing it. Every stored answer stays, and GET /v1/id/user-details still returns it. Collect again brings it back.
• Delete trait removes the declaration and its values. Stored answers stay on users’ records, and GET /v1/id/user-details still returns them as stored. Suppress instead unless the trait was never collected.

Read by on the trait’s screen lists the authored records that read the trait. While any record reads it, the trait and its values cannot be suppressed or deleted.

How users answer

Your forms read the questions from GET /v1/id/traits, which needs no credential and answers any origin:

curl https://your-tenant-host/v1/id/traits \
  -H 'x-edgekit-site-id: site_example'

{
  "traits": [
    {
      "name": "job_industry",
      "type": "list",
      "label": "Industry",
      "required": false,
      "constraints": {
        "items": [
          {
            "id": "01926f3a-8b51-7e99-9aaa-8b9c0d1e2f3a",
            "label": "Fashion",
            "externalId": "IND_FASHION"
          }
        ]
      }
    }
  ]
}

It lists every trait the user writes and your organization collects, with each list trait’s offered values. Build forms from it, not from the sign-up fields in GET /v1/id/config: those are empty for a magic link, and empty at a site that offers no EdgeKit sign-in, which still collects traits.

• At sign-up, send the answers as userTraits when signing in with an emailed code. See Sign users in.
• Later, send them to PATCH /v1/id/user-details, and read them back from GET /v1/id/user-details. See Let users manage their account.

A trait your staff writes never appears in either list, and a user cannot set it.