ProLine Partner API (1.0)

The Partner API lets an approved integration partner read and write data in a ProLine company that has shared its company key with the partner. Every request is a POST with a JSON body to a fixed path under https://api.proline.app/v1/, authenticated with two keys (see Authentication). Responses are JSON.

Endpoints are grouped by the record they work on. Record lists are paged; configuration lookups return all available options; finds return a single record (or an empty array when nothing matches); the bulk finds (/v1/find/events, /v1/find/projects, /v1/find/contacts) look up as many as 100 keys in one call; project and contact edits create or update; Edit Activity updates an existing communication activity only. Imports create records in bulk-friendly shapes and are idempotent on an external_id you supply.

Two keys travel as request headers on every call:

A request with a missing or unknown key is refused with 401. Rate limits (below) are per company key, so one slow integration never affects another company's.

Keep both keys server-side. The company key in particular grants access to that company's customer data; treat it like a password.

Limits are enforced per company key and per path, as a fixed interval between calls. A call inside the interval is refused with 429, a body of { "error": "Rate limit exceeded for <path>. Try again in <n> seconds." } and a Retry-After header carrying the same wait in whole seconds. Concurrent calls to one path are not admitted together: one is accepted and the rest are refused, so send calls to a path in sequence and wait out Retry-After before retrying.

Paged record lists return up to 100 records per page; a larger limit is clamped to 100, except List Events, which rejects it. List Events uses cursor pagination and limits source events checked before filtering. Configuration lookups do not accept pagination.

The existing record and configuration lists (excluding the claims API lists and /v1/list/events) accept optional created_after, created_before, and updated_after timestamps. Supply a valid full ISO datetime with a timezone; missing or null means no bound. Boundaries are inclusive and combined with AND. An update bound may be later than a creation upper bound. Filters apply before pagination and counts.

Record lists use newest-update-first order with updated_after; otherwise they retain creation-time order. Lookups retain display order and folders retain tree order. Activities missing an update timestamp do not match. These existing timestamps are not a complete related-record or deletion feed. Keep a small overlap between polls and deduplicate returned IDs; page/limit pagination is not a snapshot during concurrent changes.

/v1/list/events instead accepts inclusive start_after and start_before bounds on the event's scheduled start time. It includes historical events and orders them oldest first. Follow next_cursor while has_more is true, even when a filtered page has no results.

Two conventions exist, for historical reasons, and each endpoint says which it follows:

Direct. The newer endpoints (every /v1/list/* path, /v1/find/activity, /v1/find/events, /v1/find/projects, /v1/find/contacts, /v1/edit/activity) answer with the record data as the whole body and a meaningful HTTP status: 200 on success, 400 for an invalid request, 401/403 for a key problem, 429 when rate limited. Edit Activity also returns 404 for a missing activity and 409 for an association conflict or paused automations.

Wrapped. The original endpoints answer 200 whatever happened and wrap the result in a fixed envelope:

{
  "isBase64Encoded": false,
  "statusCode": 200,
  "statusDescription": "200 OK",
  "headers": { "Content-Type": "application/json" },
  "body": { ... }
}

The result, including any error the backend reported, is in body, and the HTTP status says nothing about whether the call worked. Where the failure is reported depends on the endpoint. The finds answer with an empty array when nothing matches. The activity creates and the event endpoints put it at body.error. The project/contact edits and imports (/v1/edit/project, /v1/edit/contact, /v1/import/*, /v1/files/create_project_file) answer body.status: "success" whatever happened and put the outcome in body.response: body.response.error is true on a rejection and body.response.status says why. Each endpoint's 200 response lists the exact keys and gives a rejected example; check those before treating the call as successful. Only errors raised before the request reaches the backend (an unknown key, a rate limit, an invalid JSON body, an unknown body key) carry a real HTTP status and a flat { "error": "..." } body.

Backend errors on the direct endpoints use { "success": false, "error": { "code": "BAD_REQUEST", "message": "..." } }, with a code appropriate to the failure. Each endpoint documents its statuses.

Ids in responses are ProLine ids (opaque strings). Where a company was migrated from the original ProLine platform, requests may also use that platform's legacy ids for the same records, and activity records of migrated data still report their legacy ids. Treat every id as an opaque string.

Projects have field numbers 1 to 7 and contacts 1 to 3, as in the original ProLine platform. Find and import endpoints name them custom_field_1 to custom_field_7 for a project and custom_field_1 to custom_field_3 for a contact; Edit Project names them project_custom_field_1 to project_custom_field_7 and Edit Contact custom_field_1 to custom_field_3. Each number addresses a text custom field. A company gives a text custom field a number in ProLine under Settings, on the custom field itself (its Zapier field number). Companies migrated from the original platform have numbers set for the fields they had there. Fields created in ProLine have no number until the company sets one, and this API cannot read or write them until then.

Find responses return the value of the field that holds each number, or "". List Projects does not include these values. Edit requests write to the field that holds the number and create a text field named "Custom Field N" when no field holds it, so a write never loses a value; a value sent for a number whose field the company deleted is skipped. Import requests write only to live fields that already hold the number; unassigned and deleted slots are skipped.

/v1/list/custom_field_definitions reports every numbered slot for the requested entity_type (project or contact), its label, and whether it is live, deleted, or unassigned. It does not create fields.

The project category/type/service/tag/area, contact type/tag, lead source, organization stage/type, location, and user lookups return direct arrays. Send optional date filters, an empty body or {}. Pagination is not accepted. Custom-field definitions require entity_type and return an { entity_type, results } object containing all seven project slots or all three contact slots. With date filters, a matching definition returns the complete slot snapshot; no matches returns results: []. Definitions that were deleted or lost their slot assignment participate in detection.

Lookup IDs are native ProLine IDs. Optional strings are null when unset, and unset flags are false. Archived options are excluded. User lookup includes invited members and regular or limited seats, while excluding staff, disabled users, removed members, and pending or failed removals. A user's role is their permission profile's exact name, or null. Organization types identify organization pipelines.

These lookups always require a known active partner key and company API access. Paused automations do not block them. Ordinary lookup sources above 1,000 records return HTTP 400 with backend error code LOOKUP_TOO_LARGE instead of a partial list. Custom definitions apply that source cap only with effective date filters. Conflicting custom-field definitions return HTTP 409 with code LOOKUP_CONFLICT when building a snapshot.

Claims have separate create and edit operations; none of these endpoints upserts. Native ProLine IDs identify records. A claim's external_id belongs to the authenticated company and integration and can be used by find/claim instead of claim_id.

Every write requires an Idempotency-Key header containing 8–200 printable non-space ASCII characters, except edit/claim_items with dry_run: true. Retry a lost response within 24 hours with the identical body and the same key. Receipts expire after 24 hours; later retries can execute again. Reusing an unexpired key with a changed body returns a conflict. Edits and deletions require the current resource version as expected_version; bulk item edits and deletions carry one token per entry. A stale version returns HTTP 409. Item batches contain 1–100 entries and succeed or fail atomically.

Claims lists use cursor and limit (maximum 100), not page numbers or the common record date filters above. Always follow next_cursor while has_more is true, including empty result pages, and keep filters and credentials unchanged. Lists are not snapshots or changefeeds. List Claims returns compact headers and phases; Find Claim adds groups and financial totals; List Claim Items returns paginated line items and mappings.

Phase progress is controlled by stage_id. Use initial to identify a virtual legacy Initial phase and native IDs for persisted phases. The phase's stage category is draft, awaiting_carrier, action_required or closed.

PDF extraction and export return HTTP 202 document receipts. Poll List Claim Documents for queued, processing, completed or failed status and the output URL or error; ordinary attachments are ready. Extraction requires AI estimate access and an existing project PDF of at most 50 MB, an empty phase in the Draft stage, additional_only: true, and the claim's current version. Acceptance is not completion. JSON requests are limited to 1 MiB. Existing company API access checks and the five-second company/path rate limit apply to every claims route.

ProLine can call your endpoint when records change. Outbound webhooks are configured by the company in ProLine, not through this API; see ProLine Webhooks.

Claims support claim_created, claim_updated, claim_status_change, claim_assignee_change and claim_deleted. Phase, item, group and attachment changes use claim_updated; there are no separate submission or PDF-completion event types. Use List Claim Documents to poll PDF jobs.

Claim payloads carry schema_version: 1, event_id, event_type, occurred_at (UTC ISO timestamp), company_id, source and data. The source identifies an application or partner action; data contains claim and project IDs plus the claim status, assignee and event-specific changes. Delivery uses the saved event snapshot. Deduplicate event_id and tolerate repeated or out-of-order deliveries. Fetch current state when needed instead of treating delivery order as record order.

Claim webhook requests include X-ProLine-Event-Id and X-ProLine-Signature: t=<unix-seconds>,v1=<hex-signature>. Verify HMAC-SHA256 using the webhook signing secret and the exact UTF-8 bytes of <timestamp>.<event-id>.<raw-request-body>. Compare signatures in constant time and reject stale timestamps according to your receiver's replay window. Do not parse and reserialize the body before verification.

A 2xx response acknowledges delivery. Network failures, 408, 429 and 5xx responses are retried with backoff, for at most seven attempts within 24 hours; other HTTP failures stop delivery. Redirects are not followed.