Skip to main content
GET
/
agents
Retrieve all the agents
curl --request GET \
  --url https://api.getfernand.com/agents \
  --header 'X-API-Key: <api-key>'
[
  {
    "id": 12345,
    "email": "richard.hendricks@piedpiper.com",
    "is_paying": true,
    "is_removed": false,
    "name": "Richard Hendricks",
    "firstname": "Richard",
    "notification_email": "richard.piper44@gmail.com",
    "timezone": "America/Los_Angeles",
    "signature": "<p>Best regards,<br>Richard H.</p>",
    "avatar": "https://www.gravatar.com/avatar/6d918cc24709975e61413ea4c2fb93f6?s=80&d=404",
    "dark_mode": true,
    "is_mfa_enabled": false,
    "is_current_user": true,
    "roles": [
      "conversation.create",
      "conversation.reply",
      "teammate.invite"
    ],
    "owner": false,
    "prev_next": "historical",
    "newsletter": true,
    "notifications": {
      "BROWSER": {
        "INCOMING_EMAIL": true,
        "MENTIONED": true
      },
      "EMAIL": {
        "INCOMING_EMAIL": true,
        "ASSIGNED_ACTIVITY": false
      }
    },
    "ai_prompt_answer": "Your name is ${agent_firstname}. Reply to ${contact_name} concisely.",
    "fernand_hash": "abc123def456...",
    "bounce_error": "Mailbox full",
    "custom_inboxes": [
      {
        "key": "60977abb694a6b2061de23fe26429ace",
        "name": "Inbox",
        "query": {
          "assigned": "me+none",
          "is": "opened",
          "order": "priority"
        }
      }
    ],
    "lock_reason": "email",
    "locked_ts": 1234567890000
  }
]
Returns a list of all active agents in the organization.

Authorizations

​
X-API-Key
string
header
required

Authenticate your account by including your secret key in API requests. You can manage your API keys in the Dashboard.

Authentication to the API is performed by using the HTTP Header X-API-Key.

Query Parameters

​
complete
boolean

If true, includes roles and owner status in the response.

Response

Successfully retrieved the list of agents.

​
id
integer<int64>
required

Unique identifier for the agent

Example:

12345

​
email
string<email>
required

Primary email address of the agent

Maximum string length: 250
Example:

"richard.hendricks@piedpiper.com"

​
is_paying
boolean
required

Whether this agent occupies a paid seat in the organization

Example:

true

​
is_removed
boolean
required

Whether this agent has been removed from the organization

Example:

false

​
name
string | null

Display name of the agent

Maximum string length: 250
Example:

"Richard Hendricks"

​
firstname
string

First name extracted from the agent's name

Example:

"Richard"

​
notification_email
string<email> | null

Alternative email for receiving notifications (if different from primary email)

Maximum string length: 250
Example:

"richard.piper44@gmail.com"

​
timezone
string | null

Agent's timezone (e.g., America/New_York, Europe/Paris)

Maximum string length: 250
Example:

"America/Los_Angeles"

​
signature
string | null

Email signature for the agent (HTML allowed)

Example:

"<p>Best regards,<br>Richard H.</p>"

​
avatar
string | null

URL to the agent's avatar image. Either at Gravatar (default) or on our CDN if imported.

Maximum string length: 250
Example:

"https://www.gravatar.com/avatar/6d918cc24709975e61413ea4c2fb93f6?s=80&d=404"

​
dark_mode
boolean | null

Whether dark mode is enabled (null means system default)

Example:

true

​
is_mfa_enabled
boolean

Whether multi-factor authentication is enabled for this agent

Example:

false

​
is_current_user
boolean

Whether this agent is the currently authenticated user

Example:

true

​
roles
string[]

List of permission roles assigned to the agent

Example:
[
  "conversation.create",
  "conversation.reply",
  "teammate.invite"
]
​
owner
boolean

Whether this agent is the organization owner

Example:

false

​
prev_next
enum<string>

Navigation preference for keyboard shortcuts (only for current user)

Available options:
historical,
natural
Example:

"historical"

​
newsletter
boolean

Whether agent is subscribed to the newsletter (only for current user)

Example:

true

​
notifications
object

Notification preferences organized by target and event (only for current user)

Example:
{
  "BROWSER": { "INCOMING_EMAIL": true, "MENTIONED": true },
  "EMAIL": {
    "INCOMING_EMAIL": true,
    "ASSIGNED_ACTIVITY": false
  }
}
​
ai_prompt_answer
string

Custom AI prompt template for generating responses (only for current user)

Example:

"Your name is ${agent_firstname}. Reply to ${contact_name} concisely."

​
fernand_hash
string | null

Secure key for signing emails in the Fernand chat integration (only for current user)

Example:

"abc123def456..."

​
bounce_error
string | null

Error message if email has bounced (only for current user)

Maximum string length: 250
Example:

"Mailbox full"

​
custom_inboxes
object[]

Custom inbox configurations (only for current user)

Example:
[
  {
    "key": "60977abb694a6b2061de23fe26429ace",
    "name": "Inbox",
    "query": {
      "assigned": "me+none",
      "is": "opened",
      "order": "priority"
    }
  }
]
​
lock_reason
string | null

Reason account is locked (email, bounced, ban) - only for current locked user

Maximum string length: 250
Example:

"email"

​
locked_ts
integer<int64>

Unix timestamp (milliseconds) when account was locked - only for current locked user

Example:

1234567890000