Skip to main content
GET
/
contacts
Search for contacts
curl --request GET \
  --url https://api.getfernand.com/contacts \
  --header 'X-API-Key: <api-key>'
[
  {
    "id": 12345,
    "email": "richard.hendricks@piedpiper.com",
    "name": "Richard Hendricks",
    "firstname": "Richard",
    "avatar": "https://api.getfernand.com/contacts/richard.hendricks@piedpiper.com/avatar",
    "company": {
      "id": 123,
      "name": "PiedPiper",
      "domain": "piedpiper.com",
      "logo": "https://api.fetchlab.net/icons/piedpiper.com",
      "url": "https://piedpiper.com"
    },
    "is_role": false,
    "is_trusted": true,
    "subscription_status": "active",
    "subscription_start": "2024-01-15T10:30:00Z",
    "financials": {
      "sources": {},
      "subscriptions": {
        "total": 123,
        "latest": {}
      },
      "payments": {
        "total": 123,
        "data": [
          {}
        ]
      }
    }
  }
]
Retrieves a list of contacts that match the provided query string. The search behavior depends on whether the query contains an ”@” symbol: if present, it searches by email only; otherwise, it searches both name and email fields. Only trusted contacts (session_uuid is null) are returned in the results.

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

​
query
string

Search query string. If contains "@", searches email only. Otherwise searches both name and email.

​
limit
integer
default:10

Maximum number of contacts to return.

Required range: 1 <= x <= 99

Response

List of contacts matching the search query.

​
id
integer<int64>
required

Unique identifier for the contact

Example:

12345

​
email
string
required

Email address of the contact, stored in lowercase and decoded from punycode if applicable

Maximum string length: 250
Example:

"richard.hendricks@piedpiper.com"

​
name
string | null

Display name of the contact, can be set locally or derived from various sources. Returns local_name if set, otherwise the name field, or generates a name from the email address.

Maximum string length: 250
Example:

"Richard Hendricks"

​
firstname
string | null

First name extracted from the contact's full name

Example:

"Richard"

​
avatar
string<uri>

URL to the contact's avatar image, fetched from Gravatar or domain favicon

Example:

"https://api.getfernand.com/contacts/richard.hendricks@piedpiper.com/avatar"

​
company
object

Company information associated with the contact's email domain

​
is_role
boolean

Indicates if the email is a role-based address (e.g., support@, info@, contact@)

Example:

false

​
is_trusted
boolean

Indicates if the contact is trusted (Untrusted contacts come from unverified live chat sessions).

Example:

true

​
subscription_status
enum<string> | null

Current subscription status from payment processor, only available when complete serialization is requested

Available options:
active,
past_due,
unpaid,
canceled,
churned,
incomplete,
trialing
Example:

"active"

​
subscription_start
string<date-time> | null

Timestamp when the subscription started (UTC), only available when complete serialization is requested

Example:

"2024-01-15T10:30:00Z"

​
financials
object

Financial information including payment sources, subscriptions, and payment history, only available when complete serialization is requested