Factorial's integrations framework is organised by domain — payroll and finance today — and each domain defines a set of capabilities, each with a direction and the Factorial endpoints behind it. This skill takes one external system's specification and works out, capability by capability, which vendor endpoints implement it and how every field maps between the two APIs.

The output is an integration mapping document. It serves two readers at once: whoever decides whether the integration is worth building, and whoever then builds it. The first needs the verdicts; the second needs the endpoint sequence and the field mapping. Both depend on the same rule — cite or downgrade: a mapping row, an endpoint or a verdict that cannot be pointed at in the vendor's specification does not go in the document as fact.

The capabilities are defined in Factorial's API documentation, one page per domain:

Read the page for the domain in scope at the start of every analysis. Each one lists the domain's capabilities, the direction of each, what it covers, and links to the Factorial endpoints involved. Those pages are the source of truth: analyse every capability they list, use the direction they state, and take Factorial field names from the endpoint references they link to. Do not work from memory of what a payroll or finance integration usually contains — the real lists differ from the intuitive ones, and a mapping built against the wrong capability set looks exactly as convincing as a correct one.

The URLs are versioned. Use the version the requester names, otherwise the one above, and record which version you used in the document's header, since field names and capabilities can change between versions.

If a page can't be fetched, stop and say so rather than improvising the capability list.

Decide which domain the vendor belongs to: a payroll engine is payroll; an accounting system or ERP is finance. Some systems span both — an ERP with a payroll module — in which case analyse each domain and produce one document per domain. If the system fits neither, say so and stop; forcing it into a domain produces a mapping nobody can use.

State the classification and the reason in one line at the top of the document. Don't block on the requester to confirm it; if it was a judgement call, say so and carry on.

From the domain page, build the working list: every capability, its direction, and the Factorial endpoints it links to. Then follow those endpoint links for the fields — you cannot map what you have not read. Read them per capability as you reach it rather than all upfront; the domain pages link to many endpoints and most of them serve only one capability.

Also carry forward anything the page says that constrains the whole domain: ordering or setup sequences (which records must exist before others can be created), identifiers Factorial requires on writes (such as an on records posted into Factorial), and incremental-sync parameters. These shape the endpoint sequence in the document, not just individual rows.

Build a factual inventory before mapping anything. Going capability-first means looking for the endpoint you expect and finding something adjacent to it.

For an API specification — OpenAPI/Swagger, a developer portal, a PDF guide — record one row per operation: method, path, what it does, request and response fields with their required flags, and where each came from (, section, page). Those references become the citations.

Read the field documentation and the examples, both. Descriptions tell you what a field means; examples frequently tell you what it actually takes — the date format, the real enum values, how a nested object is shaped, which fields are populated together, a field that appears in the example but was never documented in the schema. Examples often complete behaviour the schema leaves open, so use them. Where an example contradicts the schema, report the contradiction rather than silently picking one.

In a schema, slow down for composition (the real list is the union of all branches) and for a pointing back at its own ancestor (a relationship modelled as a nested object instead of an id — usually unusable, and worth a spec-quality note).

For a file specification, the same inventory in file terms: each record type or layout stands in for an endpoint, each column for a field — with mandatory flags, types, lengths, code lists, the key linking records across files, delivery mechanism, and any acknowledgement or error file.

These are claims about what the specification does not contain, and they decide capabilities as often as its contents do. Verify each against the whole file rather than an impression — count or when the file is long.

Report what they return, including nothing: "no list endpoint supports incremental filtering" is a finding, not a blank.

Direction decides what to look for on the vendor side:

Outbound — Factorial is the source. We read from Factorial's endpoints and write into the vendor, so the vendor needs write endpoints ( to create, / to update) that accept what the Factorial read endpoints return.

Inbound — the vendor is the source. We read from the vendor and write into Factorial, so the vendor needs read endpoints (, ideally paginated and filterable by modification date) that return what Factorial's write endpoints require.

A rich read API contributes nothing to an outbound capability, and a rich write API nothing to an inbound one. That mismatch is the most common way a vendor that looks well covered turns out not to be.

For each capability, identify the vendor endpoints that implement it and put them in the order an implementation calls them — including the supporting calls that make the main one possible: resolving a legal entity or cost-centre id before a create, reading back the vendor's identifier after it, looking up a code list. Then check the fields, not just the endpoints: a exists in almost every HR API, and whether it can carry a Factorial new hire is decided entirely by its fields.

This is the core of the document. For each capability, map every field that carries data between the two systems, in the direction the data flows.

For each row record: the source field and the destination field, as full paths (; ); whether the destination requires it; the transformation, if any; and the evidence — the schema, the documentation text, or an example.

Transformations are where integrations actually break, so be specific about them:

Then list the two kinds of gap, separately, because they mean different things:

Never invent a vendor field to complete a row. An unmapped row is a finding; a plausible field name that isn't in the spec is a defect in the document.

Three verdicts per capability.

Fully supported — the vendor exposes every operation the capability needs in the right direction, every field the destination requires has a source, and the record can be identified again on the next sync. Reachable only when the specification is explicit about all of it.

Partially supported — the operations exist but something needed does not: destination-required fields with no source, no update or correction path, no way to match records on the next sync, no effective dating where the data is time-dependent, a code list with no published values. Every partial verdict states the limitation and a viability judgement — shippable as-is or needs the gap closed first, and what closing it takes.

Not supported — the specification doesn't cover it: the operation or entity is absent, the spec is silent, or the only route is manual work in the vendor's UI. Absence and silence land in the same place because the consequence is the same — we can only build against what is documented. Note in the capability section whether the spec rules it out or is merely silent, since silence is a question for the vendor that could change the verdict.

The line between the last two: a missing field makes a capability partial; a missing operation or entity makes it not supported. Silence about one detail inside a capability that otherwise works — whether re-sending replaces or accumulates, say — is partial, with the detail named as the limitation.

Follow . Fill every section; write "none" rather than dropping one, so a reader can tell "nothing to report" from "not analysed".

The capability summary comes first, because it is what the decision-maker reads. Then one section per capability — every capability the domain page lists, including the unsupported ones, so it is visible that each was assessed. Each section carries the endpoint sequence, the field mapping, the gaps and the verdict. The field mapping is the part an engineer will build from, so it must be complete for the fields in scope and exact about paths and transforms.

Close with the vendor questions, ordered by how much each answer would change the plan, merging any a single conversation would settle.

Save as .