> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Subscriber Attributes

> List the custom attribute names your contacts use, with value types and examples

Lists the custom attributes in use across your account. Use it before you [create](./create) or [update](./update) a subscriber so you reuse existing names and send values of the same type. For example, if `zip` is a `string`, send `"02134"` rather than the number `2134`, which would drop the leading zero.

Value types and examples come from up to 100 of your most recent contacts that have custom attributes. Names that only older contacts carry are listed too, after the sampled ones, with `sampledContacts` set to `0`. Those come from an account-wide attribute index that returns up to the 500 most widely used names. Reserved profile fields such as email, first name and last name, and internal attributes, are not listed.

Requires the `subscribers:read` scope.

## Request

<ParamField query="includeNested" type="string" default="false">
  Set to `true` to also list nested paths such as `profile.tier`. Must be `true`
  or `false`.
</ParamField>

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/subscribers/attributes" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Response

<ResponseField name="attributes" type="array">
  Attributes seen on the sampled contacts, most common first, followed by names
  that only older contacts carry.
</ResponseField>

<ResponseField name="attributes[].key" type="string">
  Attribute name, or a dot path such as `profile.tier` when
  `includeNested=true`.
</ResponseField>

<ResponseField name="attributes[].valueType" type="string">
  JSON type of the example value: `string`, `number` or `boolean`. For a list
  attribute, the type of its items. Always `string` when `mixedTypes` is `true`.
  For names that only older contacts carry, an example of `true` or `false` is
  reported as `boolean`.
</ResponseField>

<ResponseField name="attributes[].isArray" type="boolean">
  Whether the attribute holds a list of values on the sampled contacts. Always
  `false` for names that only older contacts carry, because the attribute index
  does not record list shape.
</ResponseField>

<ResponseField name="attributes[].mixedTypes" type="boolean">
  `true` when the sampled contacts hold different types for this attribute, for
  example zip codes stored as numbers on some contacts and strings on others.
  `valueType` is then `string`, the only type that keeps every value intact.
  Send values with leading zeros as strings either way.
</ResponseField>

<ResponseField name="attributes[].sampleValue" type="string | null">
  An example value as text, truncated to 50 characters. List examples from
  sampled contacts show up to three items. `null` when no example is available.
</ResponseField>

<ResponseField name="attributes[].sampledContacts" type="integer">
  How many of the sampled contacts carry the attribute. `0` when only older
  contacts carry it.
</ResponseField>

<ResponseField name="sampledContacts" type="integer">
  How many recent contacts with custom attributes were sampled.
</ResponseField>

## Errors

If the account-wide attribute index is briefly unavailable, the response still succeeds with the attributes found on the sampled contacts. A `500` means the attributes could not be read at all. The request only reads data, so you can safely retry it.

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "attributes": [
      {
        "key": "zip",
        "valueType": "string",
        "isArray": false,
        "mixedTypes": false,
        "sampleValue": "02134",
        "sampledContacts": 42
      },
      {
        "key": "seats",
        "valueType": "number",
        "isArray": false,
        "mixedTypes": false,
        "sampleValue": "5",
        "sampledContacts": 18
      },
      {
        "key": "interests",
        "valueType": "string",
        "isArray": true,
        "mixedTypes": false,
        "sampleValue": "running, cycling",
        "sampledContacts": 7
      },
      {
        "key": "legacy_score",
        "valueType": "number",
        "isArray": false,
        "mixedTypes": false,
        "sampleValue": "42",
        "sampledContacts": 0
      }
    ],
    "sampledContacts": 100
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "success": false,
    "error": "includeNested must be true or false"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "success": false,
    "error": "Missing API key. Provide via x-api-key header or Authorization: Bearer <key>"
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "success": false,
    "error": "API key is missing required scope: subscribers:read"
  }
  ```

  ```json 500 Server Error theme={null}
  {
    "success": false,
    "error": "Failed to list attributes"
  }
  ```
</ResponseExample>