Help Center
How can we help?
Step-by-step answers for PVology, written for what you are trying to do.
Developer guides
- Developer guide: API authenticationSend Authorization: Bearer <credential> on every request. An API client can use an API key directly, or its client ID and secret with the OAuth 2.0 client-credentials grant at POST /api/v1/oauth/token (client_secret_basic or client_secret_post) for a 15-minute access token. Keys created before PVology Connect keep working.
- Developer guide: API error handlingEvery error is one JSON body with RFC 9457 member names (type, title, status, detail, code, correlationId, retryable, errors[] per field) and, for v1 clients, error: { code, message, correlationId }. Decide on code and retryable; quote correlationId to PVology Support. Errors never contain stack traces, SQL or secrets.
- Developer guide: API versioning and deprecationThe version is in the path (/api/v1) and in the pvology-api-version answer header. Within v1 only additions are made (new endpoints, fields, optional parameters): ignore fields you do not know. A breaking change would come as /api/v2 with at least 12 months of overlap, Deprecation and Sunset headers, a changelog entry and a migration guide.
- Developer guide: authorization and scopesEvery request passes one authorization chain: credential, client, workspace, organization policy, allowed addresses, environment, scope, owner (for writes) and the application's entitlement, then the application's own access rules for each record. Scopes are explicit, none is granted by default and none implies another.
- Developer guide: building a custom integrationTo integrate a system that has no connector: let PVology pull from its REST API with the Generic REST connection (Beta), push from it with an API client and idempotent POSTs, notify it with webhooks, or exchange files. Start in the sandbox, decide the source of truth, map and dry-run, then go live and watch health.
- Developer guide: conflict handlingA conflict is a mapped field changed on both sides since the last sync (three-way comparison with stored per-field hashes). The policy of the mapping decides: PVology wins, the other system wins, review by a person, or skip. A record in conflict is never half-written; recommendations are never applied by themselves.
- Developer guide: data mappingA mapping turns a source record into a PVology record of one contract object (for example projects.project or strategy.actual): field to field with a fixed list of typed transformations, defaults, validation and identity rules (external ID, then dedupe keys). Mappings are versioned (draft, validated, active, superseded) and activated only after a test and a dry run.
- Developer guide: data synchronizationA sync reads the other system, captures its field schema, compares each record field by field with PVology using stored fingerprints and writes only through the application's services, in bounded slices. Transient failures are retried with back-off and jitter; permanent ones become failed records; lost answers are verified before anything is sent again.
- Developer guide: how PVology Connect is builtPVology Connect is one shared integration foundation for every application: connectors (reusable definitions) and connections (one workspace's configured instance), one mapping and import engine, one sync engine, one API, one event catalog. Applications declare contracts and keep every write in their own services, with their permissions, rules and history.
- Developer guide: idempotent requestsEvery POST needs an Idempotency-Key header (16 to 80 letters, digits, - or _), one per intended action. The same key with the same body returns the same answer (idempotency-replayed: true); the same key with another body is refused with 422 idempotency_key_reused. Writes are also recognised by externalId next time, so a retry never duplicates a record.
- Developer guide: pagination, filtering and field selectionLists answer { data, nextCursor }. Ask for 1 to 200 records with ?limit= (100 by default) and pass ?cursor=<nextCursor> for the next page. Filters are listed per endpoint (for example status and updatedSince); ?fields= selects only the fields you need from those the endpoint may return.
- Developer guide: rate limits and quotasStandard allowance per API client: 120 requests a minute and 10,000 a day; Limited: 10 a minute and 1,000 a day; keys created before PVology Connect: 60 a minute; a workspace ceiling of 600 a minute. Every answer carries RateLimit, RateLimit-Policy and RateLimit-Limit/-Remaining/-Reset headers; over the limit the answer is 429 with Retry-After.
- Developer guide: receiving PVology webhooksPVology sends each subscribed event as an HTTPS POST with a JSON body and the headers PVology-Signature, PVology-Event, PVology-Delivery, PVology-Event-Id, PVology-Event-Version and PVology-Request-Id. Answer 2xx quickly; failures are retried after 1 minute, 5 minutes, 30 minutes and 2 hours, and failed deliveries can be replayed with the same event id.
- Developer guide: SCIM 2.0 integrationPVology's SCIM endpoints (/api/scim/v2/Users, /Groups, /ServiceProviderConfig, /ResourceTypes, /Schemas) follow the SCIM 2.0 protocol for the parts identity providers use: filters with and, or, not and parentheses, paging, and PATCH. A SCIM token selects the organization; provisioning answers only after PVology switches it on for that organization.
- Developer guide: secure credential managementPVology encrypts connection credentials and keeps only fingerprints of API keys, client secrets, access tokens and SCIM tokens. Every secret is shown once, never in logs, URLs, e-mails, AI facts or the Control Center. Use one credential per tool, the least access needed, an expiry, and rotation with overlap.
- Developer guide: single sign-on architecturePVology is an OpenID Connect client: authorization code with PKCE (S256), state and nonce, discovery checks, ID tokens signed with RS256, PS256 or ES256, exact issuer, audience and authorized party checks, and time checks with a 2-minute allowance. Test sign-in shows the claims without creating a session; member sign-in is switched on per organization after a joint test.
- Developer guide: source of truthEach connection and mapping has an explicit source-of-truth mode: PVology authoritative, external authoritative, PVology reads external, PVology publishes external, controlled two-way (one owner per field) or reference only. Fields owned by another system are read-only in PVology and refused through the API with field_managed_externally.
- Developer guide: the PVology API at a glanceThe PVology API (/api/v1) reads and sends data for every PVology application with an API client's credential: JSON over HTTPS, cursor paging, scopes you choose, rate limits with headers, one error model, idempotent writes that go through each application's own rules, and an OpenAPI 3.1 description at /api/v1/openapi.json.
- Developer guide: the PVology event modelPVology events are business facts such as crm.deal_won, projects.milestone_overdue, performance.actual.approved, governance.risk.created or connect.sync.completed. Each external event has integer versions, each with a fixed list of facts and a JSON Schema. GET /api/v1/events returns the catalog; endpoints pin a version per event.
- Developer guide: webhook security and signature checksPVology-Signature is t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with your signing secret>. Recompute it, compare in constant time, accept any v1 value (there are two during a secret rotation) and reject timestamps older than 5 minutes. Incoming webhooks to PVology use the same scheme.
Still need help?
PVology Support creates a request for you at once, answers ordinary questions straight away and brings in a specialist when needed.
Contact PVology →