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"
}
]
}
}
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"
}
}
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"
}
}
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.
