Integration sync
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:
- A daily or hourly cron with access to a checkpoint store (Redis, Postgres, a JSON file in S3 — anything durable).
- A live Pivotal API key.
- A CRM that lets you query records updated since a timestamp.
Shape of the sync
Mapping CRM IDs to Pivotal customers
Two patterns, pick one and stick with it:
Pattern A — store Pivotal’s id on your side (preferred)
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.
Pattern B — list and match by external id field
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.
Updating
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.
Checkpointing
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.
Throttle the worker
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.
Two-way: pulling from Pivotal
Polling Pivotal for changes uses cursor pagination (Pagination). Until webhooks ship, this is the only way:
What to put in metadata
Most 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.