> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zudo.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Accounts

> List, retrieve, and create customer accounts via the Zudo API.

## List accounts

`GET /api/v1/accounts`

Returns a paginated list of accounts in your organization.

```bash theme={null}
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

```json theme={null}
{
	"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.

```bash theme={null}
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

```json theme={null}
{
	"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.

```bash theme={null}
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.

```json theme={null}
{
	"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.

```bash theme={null}
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](/accounts/health-scoring#contact-activity). Set to `null` to clear. Cannot be in the future. |

### Response

Returns `200` with the updated account object on success.

```json theme={null}
{
	"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.

<Tip>
  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`.
</Tip>