> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pivotal.app/llms.txt.
> For full documentation content, see https://docs.pivotal.app/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pivotal.app/_mcp/server.

# Introduction

Pivotal is a customer onboarding and customer-success platform. The Pivotal API exposes the same primitives the app uses internally: **customers**, **contacts**, and **onboardings**. Use it to mirror customers from your CRM, attach contacts as you collect them, kick off onboardings on a closed-won webhook, and read back state for dashboards.

## What you can build

Backfill from HubSpot or Stripe and keep both sides in step with a nightly job.

Create a Customer, attach a primary Contact, then open an Onboarding when a deal closes.

Pull active onboardings into your BI tool or render them inside an internal app.

Both `display_id` (numeric, short) and the canonical cuid resolve at every endpoint.

## Design choices

Lists return `{ object: "list", data: [...], has_more, next_cursor }`. Objects return `{ object: "customer", id, display_id, ... }`. Errors return `{ error: { type, code, message, field? } }`. The shape never changes between endpoints.

Send an API key in the `Authorization` header. Live keys start with `pivotal_`, test keys with `pivotal_test_`. Keys are scoped to one workspace.

List endpoints accept `limit` (max 100) and `cursor` (ISO 8601 timestamp). Pass `response.next_cursor` straight back as the next request's `cursor`. No total counts — counting at scale is expensive and rarely needed.

`DELETE` returns `{ object: "deleted", id, display_id, deleted: true }` and hides the row from subsequent reads. The record stays in the database for audit. Reach out if you need a hard delete.

`id` is a cuid — stable, opaque, safe in any system. `display_id` is a small integer used in URLs like `/customers/42`. Pass either to any `{id}` parameter. New objects always return both.

## Conventions in this reference

* **Production base URL:** `https://my.pivotal.app/api/v1`
* **Content type:** `application/json` for request and response bodies
* **Dates:** ISO 8601 in UTC (e.g. `2026-05-26T17:21:09.412Z`)
* **Casing:** request and response fields are `snake_case`; SDKs convert to language-idiomatic case
* **HTTP methods:** `GET` to read, `POST` to create, `PATCH` for partial updates, `DELETE` for soft deletes — `PUT` is not used

Open the [Quickstart](/api/welcome/quickstart) when you're ready to make your first call. The whole loop — install key, create customer, attach contact, start onboarding — takes a few minutes.