Fieldmotion API Getting started

Opportunity statuses and referrals

Create a referral through mapped aliases and notify the referral team

POST /a/Referral_createData

Create a referral through mapped aliases and notify the referral team.

When to use this endpoint

Create a referral through mapped aliases and notify the referral team.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Referrals are global platform rows, not rows in a tenant-prefixed table; the scope and additional account checks described below are therefore significant.

Requires login. userID and parentID are forcibly assigned from the authenticated user/account, without an additional page or role check.

Parameters

ParameterTypeRequiredDescription
companyName / contactName / phone / email / notesStringsYesAll five must be nonblank strings. Email must pass PHP FILTER_VALIDATE_EMAIL. Text is stored as supplied; no handler length maximum is configured.
id / userID / parentID / cDate / lastEdited / editedUUID / customerID / appID / referralSource / status / signedDate / numSignedAnyForbiddenIdentity, workflow and metadata fields are not accepted on create. User/account and current server timestamps/marker are supplied by the server.

Example request

$referral = FM_api('Referral_createData', ['companyName' => 'Northwind Services', 'contactName' => 'Alex Morgan', 'phone' => '+44 28 0000 0000', 'email' => 'alex@example.com', 'notes' => 'Interested in a demonstration.']);

Example response

{"ok":1,"id":1042}

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":"missing or invalid parameter: companyName"}A required mapped field is absent, non-string or blank; the error names that alias.
{"error":"Invalid email address."}Malformed email.
{"error":"read-only field: id"}Forbidden identity/workflow/metadata key; the error names that alias.
{"error":"referral write failed"}A global insert/update fails; its global transaction rolls back.
{"error":"referral read failed"}A checked row read fails.
{"error":"referral transaction failed"}The global transaction cannot start or commit.
{"error":"referral operation failed"}Unexpected database/runtime failure.

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

Behaviour and edge cases

  • Returns integer ok and allocated integer id. Explicit IDs and trusted metadata cannot be supplied, and empty referrals no longer bypass contact validation.
  • Both creation paths require the same business/contact fields and a valid email, while retaining their distinct snake_case/mapped wire names. The legacy path ignores unrelated extra keys; mapped create rejects trusted metadata keys.
  • parent_id/user_id are the authenticated account/user. cdate and last_edited are current server datetime strings and edited_uuid identifies the creator route. Workflow values use schema defaults.
  • Checked global insertion commits before notification is attempted. Insert or commit failure returns an error and does not send the new-referral notification. No customer is created and no signing/payment action runs.

Side effects

  • Inserts the global row in a checked transaction and requests the referrals cache marker. No generic field-creation history is added.
  • After a successful commit, calls the mail service with submitted contact details and submitter/company identity. When PRODUCTION is defined, recipients are the fixed internal staff list; otherwise the current user’s email is used. The referred business is not the recipient. Mail acknowledgement is not checked or returned.

See it in Fieldmotion

CRM1

CRM1 Settings → Refer another business (pageRefer.js) creates referrals with Referral_new and lists/deletes them with Referrals_getDT/Referral_delete. The separate Customers → Referrals operator screen (pageReferrals.js) offers conversion and status/signing controls. No direct caller of this mapped creator was found in the reviewed CRM1 source.

CRM2

CRM2 Settings → Refer another business (pageRefer.js) uses Referrals_getDataTable with Referral/Referrals widget prefixes, mapped detail/update helpers and individual Referral_delete calls. Its custom Create form still calls Referral_new, not Referral_createData. Layout’s referral registration points generic creation at Referral_createData, but the reviewed page’s visible custom form overrides that with Referral_new. Use the example request to exercise this specific mapped contract.

Related endpoints