Objects

Retrieve contacts

List contacts with cursor pagination and optional properties, associations, and search filters.

Overview

Use this endpoint to read contacts in pages. If properties is omitted, the default response includes firstname, lastname, email, phone, and lifecyclestage. Associations are returned only when you request them. It requires public api oauth access token authentication and the crm.contacts.read scope.

GET/api/crm/objects/contacts

cURL

GET

bash

curl --request GET \  --url 'https://crm.notifyy.io/api/crm/objects/contacts?properties=firstname%2Cemail%2Cphone&associations=company%2Cdeal&search=jane&limit=25' \  --header 'Authorization: Bearer nfy_public_api_access_token'

Authorization

Public API OAuth access token

crm.contacts.read

Sample Request Body

This endpoint does not require a request body.

Sample Response

json

{  "success": true,  "message": "Contacts retrieved successfully",  "data": {    "contacts": [      {        "id": 55,        "properties": {          "firstname": "Jane",          "email": "[email protected]",          "phone": "+1-555-0101"        },        "associations": {          "company": [            {              "id": "456",              "type": "contact_to_company"            }          ]        }      }    ],    "pagination": {      "nextCursor": "eyJ2ZXJzaW9uIjoxLCJyZXNvdXJjZSI6ImNvbnRhY3RzIiwiLi4u",      "hasMore": true    }  }}

Status Codes

Code	Description
200	Contacts were returned.

Headers

AuthorizationstringRequired

Public API OAuth bearer token.

Example: Bearer nfy_public_api_access_token

Object	Description
Authorization string	RequiredPublic API OAuth bearer token. Example: Bearer nfy_public_api_access_token

Query parameters

propertiesstringOptional

Comma-separated property internal names to return. Duplicate values are deduplicated.

Example: firstname,email,phone

associationsstringOptional

Comma-separated associated object types to include.

Example: company,deal

searchstringOptional

Search string forwarded to the CRM contact query service.

Example: jane

cursorstringOptional

Opaque cursor returned by a previous list response.

limitintegerOptional

Page size. Defaults to 50 and the maximum is 100.

Example: 25

Object	Description
properties string	OptionalComma-separated property internal names to return. Duplicate values are deduplicated. Example: firstname,email,phone
associations string	OptionalComma-separated associated object types to include. Example: company,deal
search string	OptionalSearch string forwarded to the CRM contact query service. Example: jane
cursor string	OptionalOpaque cursor returned by a previous list response.
limit integer	OptionalPage size. Defaults to 50 and the maximum is 100. Example: 25

Response fields

successboolean

Whether the request succeeded.

Example: true

messagestring

Human-readable result message.

Example: Contacts retrieved successfully

data.contactsobject[]

List of matching contacts.

data.contacts[].idinteger

Contact record ID.

Example: 55

data.contacts[].propertiesobject

Requested contact properties keyed by internal name.

data.contacts[].associationsobject | null

Associated records grouped by object type when requested.

data.pagination.nextCursorstring | null

Cursor for the next page. Pass it back exactly as received.

data.pagination.hasMoreboolean

Whether another page is available.

Example: true

Object	Description
success boolean	Whether the request succeeded. Example: true
message string	Human-readable result message. Example: Contacts retrieved successfully
data.contacts object[]	List of matching contacts.
data.contacts[].id integer	Contact record ID. Example: 55
data.contacts[].properties object	Requested contact properties keyed by internal name.
data.contacts[].associations object \| null	Associated records grouped by object type when requested.
data.pagination.nextCursor string \| null	Cursor for the next page. Pass it back exactly as received.
data.pagination.hasMore boolean	Whether another page is available. Example: true