Fieldmotion API Getting started

Programme Contracts

Read Programme Portal grants

POST /a/ContractProgramme_portalAccess

Read the Customer’s explicit Programme QI and Job Progress permission bits.

When to use this endpoint

Inspect the logged-in Portal Customer’s grant record, or its parent record, before an administrator changes access. These grants are separate from Contract-level Portal switches.

Send operation fields inside one JSON-encoded data object. When data is present it replaces top-level operation fields; otherwise the handler accepts the top-level request. String data is limited to 2 MB. Reserved transport/internal keys are removed. Malformed or non-array JSON becomes an empty input, so validate JSON before sending.

Authentication and permissions

Authenticate with a signed API key or logged-in CRM session; session requests follow dispatcher CSRF checks. API-key requests use the key owner’s identity and permissions.

Requires the Contracts entitlement (features & 64), features2.contractProgrammes and Contracts View. Also requires features2.contractProgrammePortal.

All storage belongs to the authenticated tenant. Contract operations follow the actor’s recursive HR manager/team scope, or the configured TeamAccess Contract/Department policy. Client administrators have broad Contract scope; private Programme and route ownership still applies. Active assignees must be within the permitted team.

The tenant must have the Programme storage upgrade (foundation 803; independent route ownership 804 before planning). Requests never create or repair tables. A missing/incompatible storage failure can return an initialization/storage error or Contracts operation failed. Check the saved state before retrying.

Parameters

ParameterTypeRequiredDescription
customer_idPositive integer or digit stringYesNon-deleted Customer/Site linked to an in-scope Programme Contract, or the direct parent of a linked Customer. TeamAccess Customer scope also applies.

Example request

$result = FM_api('ContractProgramme_portalAccess', [
	'data' => json_encode([
		'customer_id' => 1042,
	]),
]);

Example response

{
  "ok": 1,
  "customer": {
    "id": "1042",
    "name": "Example Client",
    "parent_id": "0"
  },
  "qi": 1,
  "progress": 1
}

Errors and unusual responses

ResponseCondition
{"error":"not logged in"}No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
{"error":"Programme Contracts is not enabled"}Workspace flag or Contracts entitlement is disabled.
{"error":"Permission denied"}Contracts View or the required action permission is unavailable.
{"error":"This Contracts capability is not enabled"}The operation’s additional feature flag is disabled.
{"error":"Customer is unavailable or outside your Contracts"}No scoped linked Customer/parent.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • Requires workspace/Portal feature and Contracts View; the read itself is not client-admin-only, although CRM2 exposes the editor only to administrators.
  • Returns qi from customer_portal bit 256 and progress from bit 512, each integer 0/1, plus Customer identity. It does not calculate effective Portal access.
  • Actual Portal data still needs the enabled capability, Contract portal_qi/portal_progress, authenticated Customer/Site scope and applicable Form/status visibility. A stored bit alone does not grant every Job/PDF.

See it in Fieldmotion

CRM1

No direct caller was found in CRM1 source. This workflow is implemented by the opted-in CRM2 Programme Contracts workspace.

CRM2

In Programme Contract → Sites → Portal Access, filter for ContractProgramme_portalAccess. Parent Customer Access opens a separate grant record. Only administrators see this editor.

Related endpoints