Skip to main content

Fetch one example value for one CRM extra key (admin)

POST 
/api/integrations/crm/:provider/extra-fields/sample

WHAT DOES THIS VENDOR KEY ACTUALLY HOLD — one example, for one key, because a human pressed the button on that row of the extra-field mapping screen.

The screen used to show two examples and they were hard-coded in the Stella adapter (language → "Türkçe", country → "Türkiye"): nothing was ever read from a clinic, so the keys an operator has to size a field against — card_no, national_number, customer_type — showed nothing at all, and the two that did show something were a claim about a clinic nobody had asked. Those entries are gone; this endpoint replaced them.

Examples are patient data, so nothing is fetched when the screen opens. One key is read when somebody asks for that key. The value is never stored — not cached, not written to a link's payload, not logged, not audited — the response carries Cache-Control: private, no-store, and it is a POST rather than a GET so the answer cannot sit in a url, a browser history or a proxy cache, and a refresh cannot silently re-spend the clinic's api budget.

The read walks up to 5 of the tenant's own linked contacts through the provider's "one person by reference" call, stopping at the first record that has anything in the key — a field one patient left blank is filled on the next. Each call is metered against the tenant's interactive read budget.

"We looked and found nothing" and "we could not look" are different answers, and outcome keeps them apart: blank (read examined records, empty in every one) is the only value that entitles anyone to say the key is unused, while no_linked_records, not_configured, connection_disabled, budget, provider_unreachable, rate_limited, unsupported and unknown_key all mean the question was not answered.

Send field to have the example judged against the type of the field the operator is pointing the key at: refusal then carries the same verdict the projection would reach per record — a select of tr/en refuses Türkçe. Advisory only; nothing is blocked.

A 422 carries the machine key invalid_extra_key or unknown_field. Requires integrations.manage and the integration_crm feature.

Request​

Responses​

The answer — a value, or the honest reason there is none.