Fieldmotion API Getting started

Programme Contracts

Save Programme Portal grants

POST /a/ContractProgramme_savePortalAccess

Change the Customer’s two Programme Portal bits while preserving legacy access.

When to use this endpoint

Read portalAccess for the exact Portal login Customer first. Configure Contract-level views separately. Send both desired flags: omission clears that flag.

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. Requires Contracts Edit.

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.

Only a client administrator may perform this operation, in addition to the permissions above.

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.
qi0/1 or booleanNoDefault 0; sets positive customer_portal bit 256.
progress0/1 or booleanNoDefault 0; sets positive customer_portal bit 512.

Example request

$result = FM_api('ContractProgramme_savePortalAccess', [
	'data' => json_encode([
		'customer_id' => 1042,
		'qi' => 1,
		'progress' => 1,
	]),
]);

Example response

{
  "ok": 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":"Client administrator access is required"}Actor lacks administrator status.
{"error":"Expected Yes or No"}Flags are not booleans, 0/1 or their digit strings.

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

Behaviour and edge cases

  • Only the two positive bits are replaced; all other legacy permission bits and unrelated Customer metadata are preserved. This grants/revokes the exact record, not an automatic edit to every child.
  • Saving qi does not itself require the QI authoring gate; actual Portal QI access also requires that capability and Contract/Form/status checks.
  • This does not create a Portal login, reset credentials or change Contract configuration. Revocation is checked fresh by Portal consumers.

Side effects

  • The service serializes writes on the tenant owner in a transaction. Validation, persistence, audit or TeamAccess outstanding-Job access failures roll back that transaction. Successful changed writes refresh linked Contract/Customer sync timestamps and shared mobile update markers, then invalidate CRM caches after success. These operations do not create schema or enable account features.
  • Updates customer_portal inside preserved Customer metadata and last_edited; audits customer_portal_access_saved. No email or credential changes occur.

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

As client administrator, open Programme Contract → Sites → Portal Access, set both checkboxes and Save. Filter for ContractProgramme_savePortalAccess.

Related endpoints