The Four Action Types
Every action is one of four types. Choosing the right one is most of designing a custom endpoint well.
Where to find it
Architect Panel → Integration & Connections:
- API Server — where actions are configured
Architect Panel → Data:
- Datastores — what the fetch actions read
- Data Extraction — the ingestion pipeline the fourth type hands to
Fetch a row
Returns a single record. The right choice when the caller knows which one they want — a lookup by reference, a status check.
Fetch all rows in a table
Returns a set. Useful for reference data and small collections.
Be careful with it on anything large. A caller fetching an entire datastore on every request is a pattern that works in testing and becomes a problem at volume, and it is the commonest cause of an integration that gets slower as your data grows. Where a caller needs a subset, giving them a narrower endpoint is kinder than letting them filter client-side.
Run a PHP callback function
Hands control to your own code. The most capable option and the one to justify.
It is right when the operation is genuinely logic rather than data movement — a calculation, a decision, a call out to something else. It is wrong as a default: code in a callback is invisible to everybody reading the configuration, so business rules that live there are rules nobody will find.
If you can express something as configuration instead, do.
Perform data extraction
Passes the payload to an extraction definition, which maps and transforms it into a datastore.
This is the best answer for "a partner posts us structured data". The mapping lives in the extraction definition where it is visible and adjustable, the formats it accepts are already handled, and every run is logged. Building the same thing as a callback means reimplementing all of that in code.
Choosing
- Returning one known record — fetch a row.
- Returning a small, bounded set — fetch all rows.
- Receiving structured data to store — extraction.
- Anything genuinely computational — callback.
Prefer configuration to code
The general principle here. The first, second and fourth types are configuration: visible, reviewable, and changeable without a deployment. The third is code. Reach for it when the others genuinely cannot do the job, not because it is the most flexible.
Each type has its own settings
An action type declares the fields it needs, so the form you fill in matches the type you chose rather than being a generic catch-all. Required fields are marked, and anything sensitive is stored encrypted.
Worked example
A partner integration uses three actions across two endpoints: extraction to receive their nightly referrals file, fetch-a-row so they can check a referral's status by reference, and one callback that computes an eligibility score — the only genuinely computational step, and the only one that needed code.
Recommendations
- Use extraction for inbound structured data, not a callback.
- Avoid fetch-all on large datastores — give a narrower endpoint.
- Justify every callback.
- Prefer configuration, because it can be reviewed.