Custom Attributes

Reminder: All queries on this page require the WORKSPACE-ID header. See Getting Started for setup.

Both creators and items can have custom attributes — fields configured by your team in the Archive UI. The API lets you discover these fields, read their values, and filter by them.

In the UI, these are the fields you see and manage in your creator profiles and content details. Learn more: Understanding Creator Attributes | Updating Creator Attributes

Discover your custom attribute fields

For creators


query GetCreatorSchemas {
  customAttributeSchemas(entity: CREATOR) {
    key
    name
    type
    options { id name }
  }
}

Example response:


{
  "data": {
    "customAttributeSchemas": [
      { "key": "full_name", "name": "Full Name", "type": "TEXT", "options": [] },
      { "key": "location", "name": "Location", "type": "TEXT", "options": [] },
      { "key": "emails", "name": "Emails", "type": "TEXT_LIST", "options": [] },
      {
        "key": "gender",
        "name": "Gender",
        "type": "SINGLE_SELECT_V3",
        "options": [
          { "id": "17a79434-ed12-46d7-9aea-33806bfa1725", "name": "Female" },
          { "id": "3b2c1d0e-fa98-4567-bcde-890123456789", "name": "Male" }
        ]
      },
      {
        "key": "age",
        "name": "Age",
        "type": "SINGLE_SELECT_V3",
        "options": [
          { "id": "a4d27f51-e484-62a9-dfbe-8766618b190f", "name": "18–24" },
          { "id": "82b05d3f-c262-40e7-bdcb-6544496f978d", "name": "25–34" },
          { "id": "93c16e40-d373-51f8-cead-7655507a089e", "name": "35–44" }
        ]
      }
    ]
  }
}

For items


query GetItemSchemas {
  customAttributeSchemas(entity: ITEM) {
    key
    name
    type
    options { id name }
  }
}

Example response:


{
  "data": {
    "customAttributeSchemas": [
      { "key": "links", "name": "Links", "type": "TEXT_LIST", "options": [] },
      { "key": "post_summary", "name": "Post Summary", "type": "TEXT", "options": [] },
      { "key": "sentiment", "name": "Sentiment", "type": "SINGLE_SELECT_V2", "options": [] },
      { "key": "collections", "name": "Collections", "type": "MULTIPLE_SELECT_V2", "options": [] }
    ]
  }
}

Using with AI:

“What custom fields do I have available for creators?” “Show me all custom attributes for items” “What are the options for the age field?”

Field types

Type	Description	Example
`TEXT`	Free text	Location, Full Name, Notes
`TEXT_LIST`	List of text values	Emails, Phone Numbers, Links
`EMAIL`	Email address	Contact Email
`PHONE`	Phone number	Contact Phone
`URL`	URL	Portfolio URL, Website
`NUMBER`	Numeric value	Rate per Post, Budget
`NUMBER_LIST`	List of numbers	Monthly Rates
`DATE`	Date	Contract Start Date, Birthday
`DATE_LIST`	List of dates	Campaign Dates
`DATETIME`	Date and time	Last Contacted, Onboarding Date
`DATETIME_LIST`	List of date/times	Meeting Times
`BOOLEAN`	True/false	Favorite, VIP
`BOOLEAN_LIST`	List of booleans	—
`SINGLE_SELECT_V3`	One option from a list (creators)	Gender, Age, Relationship Status
`SINGLE_SELECT_V2`	One option from a list (items)	Sentiment
`MULTIPLE_SELECT`	Multiple options (creators)	Labels, Category
`MULTIPLE_SELECT_V2`	Multiple options (items)	Collections
`SHIPPING_ADDRESS`	Shipping address	Creator Shipping Address (for gifting)

Note: Select types use different versions depending on the entity — V3 for creators, V2 for items. Always check the schema to confirm the correct type for your workspace.

How SELECT fields work

When you query a creator or item, SELECT fields return the option’s UUID, not the readable name:


"gender": "17a79434-ed12-46d7-9aea-33806bfa1725"

To get the human-readable label ("Female"), map the UUID against the options returned by customAttributeSchemas.

Important: You cannot filter by option name — you must always use the UUID. Run customAttributeSchemas first to get the IDs.

Filter by custom attributes

Both creators and items queries accept customAttributeConditions — the syntax is the same.

Available operators

Operator	Description
`IS`	Exact match
`IS_NOT`	Not equal
`CONTAINS`	Contains text
`DOES_NOT_CONTAIN`	Does not contain text
`STARTS_WITH`	Starts with text
`ENDS_WITH`	Ends with text
`IS_EMPTY`	Field has no value
`IS_NOT_EMPTY`	Field has a value
`MORE_THAN`	Greater than (numbers)
`MORE_THAN_OR_EQUAL`	Greater than or equal (numbers)
`LESS_THAN`	Less than (numbers)
`LESS_THAN_OR_EQUAL`	Less than or equal (numbers)
`EQUAL`	Equal (numbers)
`NOT_EQUAL`	Not equal (numbers)
`BETWEEN`	Between range (numbers)
`IS_RELATIVE_TO_TODAY`	Relative to today (dates)

Important: The type field in customAttributeConditions must exactly match the type returned by customAttributeSchemas for that key. Always run customAttributeSchemas first to confirm the correct type before filtering.

Exception: for TEXT_LIST fields (like emails), use type: TEXT with operator: CONTAINS — this is validated and works correctly.

Text fields

Use CONTAINS or IS operators:


query CreatorsByLocation {
  creators(
    first: 20
    customAttributeConditions: [
      { field: "location", operator: CONTAINS, type: TEXT, value: "United States" }
    ]
  ) {
    totalCount
    nodes { id customAttributes }
  }
}

Example response:


{
  "data": {
    "creators": {
      "totalCount": 347,
      "nodes": [
        {
          "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
          "customAttributes": {
            "full_name": "Laura Méndez",
            "location": "Miami, United States"
          }
        }
      ]
    }
  }
}

Select fields

Use IS operator with the option UUID:


query CreatorsByAge {
  creators(
    first: 20
    customAttributeConditions: [
      { field: "age", operator: IS, type: SINGLE_SELECT_V3, value: "82b05d3f-c262-40e7-bdcb-6544496f978d" }
    ]
  ) {
    totalCount
    nodes { id customAttributes }
  }
}

Using with AI:

“Find all creators located in the United States” “List creators in the 25–34 age bracket” “Show me all female creators in my workspace”