> For the complete documentation index, see [llms.txt](https://developers.frill.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.frill.co/api/reference/followers.md).
# Followers
## Follower object
Followers have the following fields
| Field | Details |
| --------------------------------------------- | ----------------------------------------------------------------------------------- |
| idx
string
| A unique identifier for the follower |
| name
string
| Name of the follower |
| email
string
| Email address of the follower |
| avatar
string
| Profile image of the follower (URL) |
| attributes
object
| Custom attributes for the follower (included when `include_attributes=true`) |
| companies
array
| Companies the follower is associated with (included when `include_attributes=true`) |
| created\_at
string
| Date the follower was created |
| updated\_at
string
| Date the follower was last updated |
`attributes` and `companies` are only returned when you pass `include_attributes=true`. Each entry in `companies` contains `id` (company source identifier, a string), `name`, `monthly_spend`, and an `attributes` object of custom company attributes.
## Endpoints
You can use the following endpoints to manage Topics
#### List followers
## List followers
> Returns a list of followers
```json
{"openapi":"3.0.0","info":{"title":"Frill API","version":"1.0.0"},"servers":[{"url":"https://api.frill.co/v1"}],"security":[{"BearerAuth":[]},{"BasicAuth":[]},{"ApiKeyQuery":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key in Authorization header with Bearer prefix (recommended)"},"BasicAuth":{"type":"http","scheme":"basic","description":"API key as basic auth username (no password required)"},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"API key as query parameter"}},"parameters":{"PageLimit":{"name":"limit","in":"query","description":"Limits the number of items on a page","schema":{"type":"integer","default":20}},"PageAfter":{"name":"after","in":"query","description":"The after cursor - used for pagination","schema":{"type":"string"}}},"schemas":{"Follower":{"type":"object","required":["idx"],"properties":{"idx":{"type":"string","description":"A unique identifier for the follower"},"name":{"type":"string","description":"Name of the follower"},"email":{"type":"string","description":"Email address of the follower"},"avatar":{"type":"string","description":"Profile image of the follower (URL)"},"attributes":{"type":"object","description":"Custom attributes for the follower (included when include_attributes=true)"},"companies":{"type":"array","description":"Companies the follower is associated with (included when include_attributes=true)","items":{"type":"object","properties":{"id":{"type":"string","description":"Company source identifier"},"name":{"type":"string","description":"Company name"},"monthly_spend":{"type":"number","description":"Monthly spend amount"},"attributes":{"type":"object","description":"Custom attributes for the company"}}}},"created_at":{"type":"string","description":"The date & time the Follower was last updated (UTC timezone)"},"updated_at":{"type":"string","description":"The date & time the Follower was last updated (UTC timezone)"}}},"Pagination":{"type":"object","properties":{"total":{"type":"number"},"before":{"type":"string"},"after":{"type":"string"}}}},"responses":{"400Error":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}}}},"paths":{"/followers":{"get":{"summary":"List followers","description":"Returns a list of followers","operationId":"listFollowers","parameters":[{"$ref":"#/components/parameters/PageLimit"},{"$ref":"#/components/parameters/PageAfter"},{"name":"include_attributes","in":"query","required":false,"schema":{"type":"boolean"},"description":"Include custom attributes in the response"}],"responses":{"200":{"description":"Successfully returned a list of followers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Follower"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/400Error"}}}}}}
```
#### Search for a follower
## Search followers
> Search for followers by email
```json
{"openapi":"3.0.0","info":{"title":"Frill API","version":"1.0.0"},"servers":[{"url":"https://api.frill.co/v1"}],"security":[{"BearerAuth":[]},{"BasicAuth":[]},{"ApiKeyQuery":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key in Authorization header with Bearer prefix (recommended)"},"BasicAuth":{"type":"http","scheme":"basic","description":"API key as basic auth username (no password required)"},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"API key as query parameter"}},"schemas":{"Follower":{"type":"object","required":["idx"],"properties":{"idx":{"type":"string","description":"A unique identifier for the follower"},"name":{"type":"string","description":"Name of the follower"},"email":{"type":"string","description":"Email address of the follower"},"avatar":{"type":"string","description":"Profile image of the follower (URL)"},"attributes":{"type":"object","description":"Custom attributes for the follower (included when include_attributes=true)"},"companies":{"type":"array","description":"Companies the follower is associated with (included when include_attributes=true)","items":{"type":"object","properties":{"id":{"type":"string","description":"Company source identifier"},"name":{"type":"string","description":"Company name"},"monthly_spend":{"type":"number","description":"Monthly spend amount"},"attributes":{"type":"object","description":"Custom attributes for the company"}}}},"created_at":{"type":"string","description":"The date & time the Follower was last updated (UTC timezone)"},"updated_at":{"type":"string","description":"The date & time the Follower was last updated (UTC timezone)"}}},"Pagination":{"type":"object","properties":{"total":{"type":"number"},"before":{"type":"string"},"after":{"type":"string"}}}},"responses":{"400Error":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}}}},"paths":{"/followers/search":{"get":{"summary":"Search followers","description":"Search for followers by email","operationId":"searchFollowers","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string"}},{"name":"include_attributes","in":"query","required":false,"schema":{"type":"boolean"},"description":"Include custom attributes in the response"}],"responses":{"200":{"description":"Successfully returned a list of followers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Follower"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/400Error"}}}}}}
```
#### Create Follower
## Create a follower
> Create a new follower
```json
{"openapi":"3.0.0","info":{"title":"Frill API","version":"1.0.0"},"servers":[{"url":"https://api.frill.co/v1"}],"security":[{"BearerAuth":[]},{"BasicAuth":[]},{"ApiKeyQuery":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key in Authorization header with Bearer prefix (recommended)"},"BasicAuth":{"type":"http","scheme":"basic","description":"API key as basic auth username (no password required)"},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"API key as query parameter"}},"schemas":{"FollowerCreate":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string","description":"Name of the follower"},"email":{"type":"string","description":"Email address of the follower"},"attributes":{"type":"object","description":"Custom attributes for the follower (key-value pairs)"},"companies":{"type":"array","description":"Array of companies the follower is associated with. Each company must contain id and name. It can also contain any custom fields (e.g., monthly_spend, plan) which are optional.","items":{"type":"object","properties":{"id":{"type":"string","description":"Company identifier"},"name":{"type":"string","description":"Company name"}}}}}},"Follower":{"type":"object","required":["idx"],"properties":{"idx":{"type":"string","description":"A unique identifier for the follower"},"name":{"type":"string","description":"Name of the follower"},"email":{"type":"string","description":"Email address of the follower"},"avatar":{"type":"string","description":"Profile image of the follower (URL)"},"attributes":{"type":"object","description":"Custom attributes for the follower (included when include_attributes=true)"},"companies":{"type":"array","description":"Companies the follower is associated with (included when include_attributes=true)","items":{"type":"object","properties":{"id":{"type":"string","description":"Company source identifier"},"name":{"type":"string","description":"Company name"},"monthly_spend":{"type":"number","description":"Monthly spend amount"},"attributes":{"type":"object","description":"Custom attributes for the company"}}}},"created_at":{"type":"string","description":"The date & time the Follower was last updated (UTC timezone)"},"updated_at":{"type":"string","description":"The date & time the Follower was last updated (UTC timezone)"}}}},"responses":{"400Error":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}}}},"paths":{"/followers":{"post":{"summary":"Create a follower","description":"Create a new follower","operationId":"createFollower","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowerCreate","required":["name","email"]}}}},"responses":{"200":{"description":"Successfully created a new follower","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Follower"}}}}}},"400":{"$ref":"#/components/responses/400Error"},"403":{"description":"Custom attributes not enabled (when attributes or companies are provided)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"},"code":{"type":"string"}}}}}}}}}}}
```
#### Update Follower
## Update a follower
> Update an existing follower
```json
{"openapi":"3.0.0","info":{"title":"Frill API","version":"1.0.0"},"servers":[{"url":"https://api.frill.co/v1"}],"security":[{"BearerAuth":[]},{"BasicAuth":[]},{"ApiKeyQuery":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key in Authorization header with Bearer prefix (recommended)"},"BasicAuth":{"type":"http","scheme":"basic","description":"API key as basic auth username (no password required)"},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"API key as query parameter"}},"schemas":{"FollowerUpdate":{"type":"object","properties":{"name":{"type":"string","description":"Name of the follower (optional)"},"email":{"type":"string","description":"Email address of the follower (optional)"},"attributes":{"type":"object","description":"Custom attributes to merge with existing attributes (key-value pairs, optional)"},"companies":{"type":"array","description":"Array of companies to merge with existing associations (optional). Each company can contain any custom fields (e.g., monthly_spend, plan) which are optional.","items":{"type":"object","properties":{"id":{"type":"string","description":"Company identifier"},"name":{"type":"string","description":"Company name"}}}}}},"Follower":{"type":"object","required":["idx"],"properties":{"idx":{"type":"string","description":"A unique identifier for the follower"},"name":{"type":"string","description":"Name of the follower"},"email":{"type":"string","description":"Email address of the follower"},"avatar":{"type":"string","description":"Profile image of the follower (URL)"},"attributes":{"type":"object","description":"Custom attributes for the follower (included when include_attributes=true)"},"companies":{"type":"array","description":"Companies the follower is associated with (included when include_attributes=true)","items":{"type":"object","properties":{"id":{"type":"string","description":"Company source identifier"},"name":{"type":"string","description":"Company name"},"monthly_spend":{"type":"number","description":"Monthly spend amount"},"attributes":{"type":"object","description":"Custom attributes for the company"}}}},"created_at":{"type":"string","description":"The date & time the Follower was last updated (UTC timezone)"},"updated_at":{"type":"string","description":"The date & time the Follower was last updated (UTC timezone)"}}}},"responses":{"400Error":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}}}},"paths":{"/followers/{followerIdx}":{"post":{"summary":"Update a follower","description":"Update an existing follower","operationId":"updateFollower","parameters":[{"name":"followerIdx","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier for the follower"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowerUpdate"}}}},"responses":{"200":{"description":"Successfully updated the follower","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Follower"}}}}}},"400":{"$ref":"#/components/responses/400Error"},"403":{"description":"Custom attributes not enabled","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"},"code":{"type":"string"}}}}}},"404":{"description":"Follower not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"},"code":{"type":"string"}}}}}}}}}}}
```
#### Delete a follower
## Delete a follower
> Delete a follower
```json
{"openapi":"3.0.0","info":{"title":"Frill API","version":"1.0.0"},"servers":[{"url":"https://api.frill.co/v1"}],"security":[{"BearerAuth":[]},{"BasicAuth":[]},{"ApiKeyQuery":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key in Authorization header with Bearer prefix (recommended)"},"BasicAuth":{"type":"http","scheme":"basic","description":"API key as basic auth username (no password required)"},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"API key as query parameter"}},"responses":{"200Success":{"description":"Request was successful","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400Error":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}}}},"paths":{"/followers/{followerIdx}":{"delete":{"summary":"Delete a follower","description":"Delete a follower","operationId":"deleteFollower","parameters":[{"name":"followerIdx","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier for the follower"},{"name":"content","in":"query","required":false,"schema":{"type":"string","enum":["delete","reassign"],"default":"delete"},"description":"Action to take with follower's content: 'delete' removes all content, 'reassign' transfers content to an anonymous user"}],"responses":{"200":{"$ref":"#/components/responses/200Success"},"400":{"$ref":"#/components/responses/400Error"}}}}}}
```