Opportunity statuses and referrals
Create an internal sales customer from an Open referral and mark it Contacted
/a/Referral_convertToCustomer
Create an internal sales customer from an Open referral and mark it Contacted.
When to use this endpoint
Create an internal sales customer from an Open referral and mark it Contacted. This is an internal operator workflow, not a general tenant integration operation.
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 tenant context and hardcodes account 32 as the internal Fieldmotion operator account. Other accounts receive the internal-use error even if they know a global referral ID. Within that account, the update/lookup is by global ID without a source-parent filter.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Positive integer string | Yes | Global referral ID. Normally must be Open (0); a completed Contacted (1) conversion with a valid linked active customer can be replayed idempotently. |
callback | YYYY-MM-DD HH:MM string | Yes | Exact valid calendar date/time, no seconds or timezone suffix. Stored as supplied. |
notes | String | Yes | Notes for the newly created customer, not copied from referral notes. May be blank. A recovery/replay does not replace an existing customer’s notes. |
Example request
$result = FM_api('Referral_convertToCustomer', ['id' => '1042', 'callback' => '2026-10-12 10:30', 'notes' => 'Call Alex about 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":"this system is only for FieldMotion use"} | Not internal account 32. |
{"error":"no ID"} | ID absent or converts to zero. |
{"error":"no callback, or callback is in wrong format"} | Missing, malformed or impossible date/time. |
{"error":"missing or invalid parameter: notes"} | Notes absent or not a string. |
{"error":"this referral was already converted into a customer"} | Non-Open status, except a valid completed Contacted replay. |
{"error":"linked customer does not exist"} | Completed conversion points to a missing/inactive customer. |
{"error":"linked customer is deleted"} | Recovery marker belongs to a deleted customer; it is not silently recreated. |
{"error":"referral company_name is too long for a customer"} | A copied contact field exceeds its customer column limit; the error names that field. |
{"error":"referral company name is missing"} | Source business name is blank. |
{"error":"referral write failed"} | Checked global write fails and rolls back. |
{"error":"referral read failed"} | Checked row read fails. |
{"error":"referral transaction failed"} | Global transaction start/commit fails. |
{"error":"referral does not exist"} | ID is missing, or the row is hidden when a workflow edit is requested. |
{"error":"customer transaction failed"} | Internal tenant transaction start/commit fails. |
{"error":"configuration write failed"} | Customer insert/history fails and rolls back before the tenant commit. |
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 internal account 32 can convert. The global source referral is locked so concurrent/replayed conversions do not create duplicate customers.
- Copies company_name to customer name, contact_name to contact_name, phone to landline and email to email. Customer notes come from the request; callback is the validated literal. Limits checked before insertion are 178/82/38/64 bytes respectively.
- Customer insert and checked referral-creation history use a tenant transaction. The global referral link/status update is checked, sets status=1/customer_id and advances last_edited/edited_uuid.
- The customer stores meta.creation.referral_id as a durable recovery marker. If the tenant commit succeeds but the separate global commit fails, a later Open-referral retry reuses that active customer rather than creating another.
- A completed Contacted conversion with an active linked customer returns the same {ok:1} envelope on replay. Other non-Open statuses still fail. A deleted recovery customer is not restored or recreated.
- Still directly inserts the internal sales customer instead of invoking Customer_new: no geocoding, default relationship setters or customer-created event dispatch is added. No automatic signing count/date/payment or email is triggered.
Side effects
- Creates one internal customer with current server timestamps, the durable referral marker, a customers cache marker and checked tenant history, then links the global referral with a referrals cache marker.
- No new-referral email, payment, generic Customer_new event or deletion-audit write occurs. Recovery reuses the marked customer without overwriting its saved contact/notes/callback values.
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. On an Open referral, choose Create Customer, supply callback date/time and notes, then save. Subsequent status editing is separate.
CRM2
The reviewed CRM2 Refer another business page does not call this internal operator endpoint. Its table displays status, signedDate and numSigned as readonly cells; that page is not an equivalent operator workflow.
Related endpoints
Referral_setStatuschanges later workflow status without creating customers.Referral_getRequestedDetailsexposes customerID for the submitting account.