The most common Pivotal integration is a cron that pulls customers from your CRM (HubSpot, Salesforce, Stripe) into Pivotal so onboarding and CS workflows have the same source of truth as your revenue dashboard.
This guide walks the pattern. It assumes:
Two patterns, pick one and stick with it:
Add a pivotal_customer_id column to your CRM (or to a sidecar table). The first time you sync a record, create the Pivotal customer and save the returned id.
The Idempotency-Key belt-and-suspenders means a retry after a network blip doesn’t double-create. The slug_taken recovery handles the case where someone created the customer manually before the sync ran.
Skip the sidecar table. On each run, list all Pivotal customers and match on hubspot_company_id (or whichever CRM ID field you use):
This works for small workspaces (< 1000 customers) but gets expensive as you grow. Pattern A scales.
Once you have the Pivotal id (or display_id), pushing updates is a PATCH:
Send only the fields you actually pulled from the CRM. PATCH is partial — omitted fields stay as Pivotal has them.
After processing a batch, save the highest crm_updated_at from the batch. On the next run, start from there:
If the worker crashes mid-batch, you re-process some records on the next run — idempotent because of PATCH.
The Pivotal rate limit is 60 req/min on a default key. A sync of 500 customers will burn through that in 8–9 minutes. Keep concurrency low:
Or use a 600/min paid key — open a ticket from inside the workspace if you need one.
Polling Pivotal for changes uses cursor pagination (Pagination). Until webhooks ship, this is the only way:
metadataMost CRM-specific data (lead source, deal owner, contract value) doesn’t have a first-class field on Pivotal’s customer model. Use the metadata JSON field — it round-trips intact:
Pivotal doesn’t introspect metadata; it’s a black box for your use. Search and filtering on metadata fields isn’t supported via the API yet.