Accounts

List accounts

GET /api/v1/accounts Returns a paginated list of accounts in your organization.

curl https://zudo.so/api/v1/accounts \
  -H "x-api-key: psk_your_key_here"

Query parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`pageSize`	integer	`25`	Results per page (max 100)
`search`	string	—	Filter by account name or `externalId` (case-insensitive substring match)
`externalId`	string	—	Filter to the account whose `externalId` exactly matches this value. Useful for reverse-lookup by your own customer identifier.
`status`	string	—	Filter by status: `active`, `onboarding`, `churned`, or `inactive`
`sortBy`	string	`name`	Sort field: `name`, `mrr`, `createdAt`, or `updatedAt`
`sortOrder`	string	`asc`	Sort direction: `asc` or `desc`

Response

{
	"data": [
		{
			"id": 1,
			"name": "Pied Piper",
			"externalId": "piedpiper",
			"mrr": 48000,
			"active": true,
			"churned": false,
			"onboarding": false,
			"logoUrl": null,
			"createdAt": "2024-03-15T08:00:00.000Z",
			"updatedAt": "2025-01-10T14:22:00.000Z"
		}
	],
	"pagination": {
		"page": 1,
		"pageSize": 25,
		"total": 47,
		"totalPages": 2,
		"hasNextPage": true,
		"hasPrevPage": false
	}
}

Get account

GET /api/v1/accounts/{accountId} Returns full details for a single account, including contacts, recent meetings, and linked requests.

curl https://zudo.so/api/v1/accounts/1 \
  -H "x-api-key: psk_your_key_here"

Path parameters

Parameter	Type	Description
`accountId`	integer	The account ID

Response

{
	"data": {
		"id": 1,
		"name": "Pied Piper",
		"externalId": "piedpiper",
		"mrr": 48000,
		"active": true,
		"churned": false,
		"onboarding": false,
		"logoUrl": null,
		"createdAt": "2024-03-15T08:00:00.000Z",
		"updatedAt": "2025-01-10T14:22:00.000Z",
		"contacts": [
			{
				"id": 1,
				"name": "Richard Hendricks",
				"email": "richard@piedpiper.com"
			}
		],
		"meetings": [
			{
				"id": 5,
				"title": "Q1 Review",
				"startAt": "2025-01-08T14:00:00.000Z",
				"endAt": "2025-01-08T15:00:00.000Z"
			}
		],
		"requests": [
			{
				"id": 3,
				"title": "SSO integration",
				"status": "Open",
				"severity": 62,
				"requestedAt": "2024-11-01T00:00:00.000Z"
			}
		]
	}
}

Returns 404 if the account is not found or does not belong to your organization.

Create account

POST /api/v1/accounts Creates a new account in your organization.

curl -X POST https://zudo.so/api/v1/accounts \
  -H "x-api-key: psk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aviato",
    "externalId": "aviato-prod-7421",
    "mrr": 12000,
    "status": "active",
    "contactName": "Erlich Bachman",
    "contactEmail": "erlich@aviato.com"
  }'

Request body

Field	Type	Required	Description
`name`	string	Yes	Account name
`externalId`	string	No	Your unique identifier for this account (e.g. your internal customer ID). Used to match incoming product-usage events to this account. Must be unique within your organization.
`mrr`	number	No	Monthly recurring revenue
`status`	string	No	`active` (default), `onboarding`, or `churned`
`contactName`	string	No	Name of an initial contact to create
`contactEmail`	string	No	Email of an initial contact to create

Response

Returns 201 with the created account object on success.

{
	"data": {
		"id": 48,
		"name": "Aviato",
		"externalId": "aviato-prod-7421",
		"mrr": 12000,
		"active": true,
		"churned": false,
		"onboarding": false,
		"createdAt": "2025-02-01T10:00:00.000Z",
		"updatedAt": "2025-02-01T10:00:00.000Z"
	}
}

Returns 400 if name is missing or empty, or if externalId is not a string. Returns a database error if externalId collides with another account in your organization.

Update account

PATCH /api/v1/accounts/{accountId} Updates fields on an existing account.

curl -X PATCH https://zudo.so/api/v1/accounts/1 \
  -H "x-api-key: psk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "piedpiper-v2",
    "contactActivityAt": "2025-06-10T14:30:00.000Z"
  }'

Path parameters

Parameter	Type	Description
`accountId`	integer	The account ID

Request body

Field	Type	Required	Description
`externalId`	string \| null	No	Your unique identifier for this account. Used to match incoming product-usage events. Must be unique within your organization. Set to `null` or `""` to clear.
`contactActivityAt`	string \| null	No	ISO 8601 timestamp of when a contact was last active. Used as a health score factor. Set to `null` to clear. Cannot be in the future.

Response

Returns 200 with the updated account object on success.

{
	"data": {
		"id": 1,
		"name": "Pied Piper",
		"externalId": "piedpiper-v2",
		"mrr": 48000,
		"active": true,
		"churned": false,
		"onboarding": false,
		"contactActivityAt": "2025-06-10T14:30:00.000Z",
		"createdAt": "2024-03-15T08:00:00.000Z",
		"updatedAt": "2025-06-10T14:35:00.000Z"
	}
}

Returns 400 if the date is invalid or in the future, or if no valid fields are provided. Returns 404 if the account is not found or does not belong to your organization.

Use this endpoint to feed contact activity data from external systems (support platforms, product analytics, etc.) into Zudo’s health score. When set via the API, this value takes priority over Vitally’s lastSeenTimestamp.

Get Started

Tasks

Meetings

Emails

Issues

Requests

Alerts

AI Features

Reporting

Integrations

Settings

Accounts

List accounts

Query parameters

Response

Get account

Path parameters

Response

Create account

Request body

Response

Update account

Path parameters

Request body

Response

​List accounts

​Query parameters

​Response

​Get account

​Path parameters

​Response

​Create account

​Request body

​Response

​Update account

​Path parameters

​Request body

​Response

List accounts

Query parameters

Response

Get account

Path parameters

Response

Create account

Request body

Response

Update account

Path parameters

Request body

Response