List or find the contacts of a list
Two modes.
Exact lookup (use it before an update or a delete): pass email OR linkedinUrl. The email is matched exactly but case-insensitively, the LinkedIn URL is compared as an exact string (a trailing slash or a missing www is a different URL). The search covers this list and the lists linked to it, returns up to 50 matches, ignores search, filters and pagination, and returns the full contact objects. The envelope then has page: 1, pageSize equal to the number of items (1 when empty) and no customVariables.
Paginated listing: without email and linkedinUrl, returns one page of the contacts stored in this list (not in linked lists), in creation order unless sortBy is set. Company rows without a contact (company-only lists) are included with rowKind: "company_only" and an id of the form co:<companyId> that the contact routes do not accept.
In paginated mode, when the list has column settings (every list created by this API or by the current app has them), each item only contains the fields of the columns visible in the list table of the app: a column hidden in the app disappears from the API response, labels is not returned and company carries no companyId. Use the exact lookup to get the full object.
Deep pages are expensive (the service sorts page x pageSize rows to serve one page): page through large lists with pageSize=100 and avoid restarting from page 1, or use the export.
Authorization
apiKey Your 48 character API key, sent as is (a Bearer prefix is tolerated). Create it at https://v3.emelia.io/settings/api.
In: header
Path Parameters
List id.
^[0-9a-fA-F]{24}$Query Parameters
Exact lookup by email (case-insensitive). Mutually exclusive with linkedinUrl.
emailExact lookup by LinkedIn profile URL (compared verbatim with the stored linkedinUrlProfile). Mutually exclusive with email.
Page number. Invalid or negative values fall back to 1.
1 <= value1Page size, clamped between 1 and 100.
1 <= value <= 10050Free-text search, 200 characters max. A full email address is matched exactly (case-insensitive). Otherwise every word must appear (case-insensitive substring) in one of firstName, lastName, fullName, email or linkedinUrlProfile; company-only rows are matched on the company name.
length <= 200Sort field. Text fields sort case- and accent-insensitively. Any other value is ignored (creation order).
Value in
- "firstName"
- "lastName"
- "fullName"
- "jobTitle"
- "email"
- "phone"
- "linkedinUrlProfile"
- "country"
- "city"
- "createdAt"
- "updatedAt"
Sort direction, used with sortBy.
"asc"Value in
- "asc"
- "desc"
Comma-separated engagement statuses (as stored on the contacts, for example SENT, OPENED, MAIL_REPLIED, ACCEPTED). The token NO_ACTIVITY matches contacts without status. Up to 30 values. Company-only rows are excluded when this filter is set.
URL-encoded JSON array of column rules (up to 10), all combined with AND. See ListsFilterRule.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/lists/list/65f1a2b3c4d5e6f760f68df4/rows?statuses=MAIL_REPLIED%2CLINKEDIN_REPLIED&filters=%5B%7B%22column%22%3A%22companyName%22%2C%22operator%22%3A%22contains%22%2C%22value%22%3A%22acme%22%7D%5D" \ -H "Authorization: YOUR_API_KEY"{ "items": [ { "id": "66f2a1b2c3d4e5f6a7b8c9d0", "firstName": "John", "lastName": "Doe", "fullName": "John Doe", "jobTitle": "Head of Sales", "gender": null, "email": "john.doe@acme.com", "secondaryEmail": null, "phone": "+33612345678", "mobilePhone": null, "linkedinUrlProfile": "https://www.linkedin.com/in/john-doe-acme", "twitterUrl": null, "country": "France", "city": "Paris", "seniority": "", "department": "", "bio": "", "profilePictureUrl": null, "company": { "companyId": "66f2a1b2c3d4e5f6a7b8c9e0", "companyName": "Acme", "companyDomain": "acme.com", "websiteUrl": "https://www.acme.com", "industry": "Software", "companySize": "51-200", "employeeCount": null, "country": "", "city": "", "linkedinCompanyUrl": "https://www.linkedin.com/company/acme", "logoUrl": "", "customFields": [] }, "labels": [], "emailVerified": "unknown", "status": "", "customFields": [ { "technicalName": "icebreaker", "displayName": "icebreaker", "value": "Loved your talk at SaaStock" } ], "createdAt": "2026-10-02T08:00:00.000Z", "updatedAt": "2026-10-02T08:00:00.000Z", "rowKind": "lead" } ], "total": 1, "page": 1, "pageSize": 1}