List Contacts

This endpoint returns a page of contacts for the authenticated account.

Endpoint

GET /v1/contacts/contacts

Authentication

Include your API key in the x-api-key header. See Authentication.

Required Scope

contacts:read

Query Parameters

Parameter	Type	Required	Description
clientId	string	No	Returns only contacts that belong to this client.
noClient	string	No	"true" returns only contacts that have no client. When set, clientId is ignored.
archived	string	No	"true" returns only archived contacts. Any other value, or no value, returns only contacts that are not archived.
all	string	No	"true" returns archived and non-archived contacts. When set, archived is ignored.
page	string	No	0-based page index. Defaults to 0. A non-numeric value is treated as 0.
pageSize	string	No	Number of contacts per page. Defaults to 25. There is no maximum.
sortCol	string	No	One of contactName, contactDescription, contactEmail, createdAt, updatedAt, Client.client_name. Requires sortDir. Invalid values are ignored.
sortDir	string	No	asc or desc (not case-sensitive). Requires sortCol. Invalid values are ignored.

See Pagination for paging and sorting rules.

Request Body

This endpoint does not accept a request body.

Example Request

cURL

curl "https://api.crewsum.com/v1/contacts/contacts?clientId=client-ghi123jkl4567890&page=0&pageSize=25" \
  -H "x-api-key: $CREWSUM_API_KEY"

JavaScript

const response = await fetch(
  "https://api.crewsum.com/v1/contacts/contacts?clientId=client-ghi123jkl4567890&page=0&pageSize=25",
  { headers: { "x-api-key": process.env.CREWSUM_API_KEY } },
);
const result = await response.json();

HTTP

GET /v1/contacts/contacts?clientId=client-ghi123jkl4567890&page=0&pageSize=25 HTTP/1.1
Host: api.crewsum.com
x-api-key: <your-api-key>

Response

On success, the API returns HTTP 200 OK.

Example Response

{
  "message": "Successfully fetched contacts",
  "data": {
    "contacts": [
      {
        "email": "placeholder@example.com",
        "type": "EXTERNAL",
        "userId": null,
        "hasPortalAccess": true,
        "id": "contact-jkl123mno4567890",
        "name": "Contact Name",
        "description": "A brief description of the contact",
        "isArchived": false,
        "createdAt": "2026-01-05T15:30:00.000Z",
        "updatedAt": "2026-02-10T09:12:00.000Z",
        "clientId": "client-ghi123jkl4567890",
        "clientName": "Client Name",
        "isDeleted": false,
        "clientDeleted": false,
        "clientArchived": false,
        "associations": [
          {
            "projectId": "project-abc123def4567890",
            "projectName": "Project Name",
            "endCustomer": "End Customer Name",
            "contactType": "MANAGER",
            "notificationLevel": "COPY_ONLY"
          }
        ],
        "supplierAssociations": [
          {
            "supplierId": "supplier-abc123def4567890",
            "supplierName": "Supplier Name"
          }
        ]
      }
    ],
    "count": 1
  }
}

Behavior

• data.contacts holds the current page. data.count is the total number of contacts that match the filters, across all pages.
• Deleted contacts are never returned.
• Without a valid sortCol and sortDir pair, contacts are sorted by updatedAt descending, then createdAt descending. Contacts that were never updated (updatedAt: null) sort last.
• contactEmail sorts by the email shown in the response, so internal contacts sort by their linked user’s email.
• email is always a string. External contacts return the stored contact email. Internal contacts return the linked user’s email. It is an empty string when neither exists.
• userId is null for external contacts. For internal contacts it is the internal <tenantId>#<userId> form, for example acme#user-a.
• Contacts without a client return null for clientId, clientName, clientArchived, and clientDeleted.
• associations lists the contact’s active project associations. endCustomer is the project’s end customer name, or null.
• supplierAssociations lists the suppliers the contact is linked to.
• updatedAt is null for contacts that were never updated.

Error Responses

Status	Meaning
500	{"message": "Error fetching contacts"}. Crewsum could not fetch contacts.

Authentication and scope failures are described in Errors.

Related Webhooks

This endpoint does not trigger a webhook.