Opportunity statuses and referrals
Submit another business as a referral and notify the referral team
/a/Referral_new
Submit another business as a referral and notify the referral team.
When to use this endpoint
Submit another business as a referral 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.
The handler requires an authenticated user ID. It assigns parent_id and user_id from that user; no extra page permission or feature setting is checked.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
company_name / contact_name / phone / notes | Strings | Yes | All four must be nonblank strings after a whitespace check. Text is stored as supplied, not trimmed. Literal '0' is rejected by the legacy form check; no handler length maximum is configured. |
email | Email string | Yes | Must be truthy and pass PHP FILTER_VALIDATE_EMAIL. Use the legacy snake_case company_name/contact_name names, not mapped companyName/contactName. |
Example request
$result = FM_api('Referral_new', ['company_name' => 'Northwind Services', 'contact_name' => 'Alex Morgan', 'phone' => '+44 28 0000 0000', 'email' => 'alex@example.com', 'notes' => 'Interested in a demonstration.']);Example response
{"ok":1}Errors and unusual responses
| Response | Condition |
|---|---|
{"error":"not logged in"} | No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs. |
{"error":"no company_name"} | company_name absent or falsey. |
{"error":"no contact_name"} | contact_name absent or falsey. |
{"error":"no phone"} | phone absent or falsey. |
{"error":"no notes"} | notes absent or falsey. |
{"error":"no email"} | Email absent, falsey or fails email validation. |
{"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 no ID. Query mapped details using an identifying filter if the ID is needed. Duplicate submissions are not deduplicated.
- 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. Open Refer another business → Create, fill all five fields and save. Inspect this call before the list reload.
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. Choose Create and complete its five-field form; the custom client callback sends the same legacy payload.
Related endpoints
Referral_createDataaccepts mapped aliases and returns an ID; it also rejects explicit trusted metadata.Referral_getRequestedDetailscan locate the created row.Referrals_getDTreloads CRM1’s list.