Introduction | Pivotal Docs

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

Sync customers from your CRM

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

Kick off an onboarding

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

Read state into dashboards

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

Use display_id in URLs

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

Design choices

Predictable envelope on every response

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.

One auth scheme: Bearer

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

Cursor pagination by created_at

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.

Soft deletes everywhere

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.

Two IDs per resource

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 when you’re ready to make your first call. The whole loop — install key, create customer, attach contact, start onboarding — takes a few minutes.