> 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 |
| avatar
number
| Profile image of the follower (URL) |
| email
number
| Email address |
| created\_at
number
| Date the follower was created |
| updated\_at
number
| Date the follower was last updated |
## 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"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developers.frill.co/api/reference/followers.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.