Data Mapping
Part of APIs and webhooks in automated workflows
Reading an API response before mapping fields
Inspect an API response's status, headers, JSON shape and field meaning before mapping values into a workflow.
Read an API response in this order: status, headers, body shape, then field meaning. Before mapping a field, identify the operation that returned it, what the response says about the operation's outcome, and what the field represents.
Start outside the JSON body
Record the request method and endpoint beside the response. Check the status code against the endpoint's documentation to understand the operation's outcome.
For an error response, use the provider's documented error format instead of looking for fields from a successful response.
Check Content-Type before treating a body as JSON. Inspect headers that affect what you read next.
A list may contain only one page: GitHub's REST API, for example, provides a link header when a response is paginated. Other APIs use different page or cursor rules.
Key API Response Elements to Verify
- Content-Type Header
- Must be `application/json` to treat body as JSON
- Pagination Indicator
- Check for `Link` header (GitHub) or cursor/page tokens in other APIs
- Error Format
- Use provider-specific error structure, not fields from successful responses
Trace an illustrative response
This invented JSON shows a reading method, not a provider payload:
{
"request_id": "req_demo_7",
"order": {
"id": "ord_demo_42",
"number": "AU-0042",
"customer": { "id": "cust_demo_9" },
"delivery_note": null
}
}
Identify the paths first. order.id and order.number are different values; neither is automatically a destination record ID. order.customer.id is nested, so reading only top-level fields will not find it.
Then distinguish presence from value. This sample has a delivery_note property set to null.
Another response might omit it or provide an empty string. Only the selected API's contract can tell you what those states mean for that operation.
API Response States: Presence vs Value
- Field Present with `null` Value`delivery_note`: null — indicates absence of a delivery note, but the field exists.
- Field OmittedNo `delivery_note` key — means the field was not returned at all.
- Field with Empty String`delivery_note`: "" — may indicate intentional blank entry, depending on API contract.
Record what each field means
| Item | Question to answer |
|---|---|
| Path and type | Where is the value, and which types can appear? |
| Business meaning | Is it an internal ID, displayed number or cross-system reference? |
| Presence | Can it be absent, null or empty? |
| Collection | Is this one object, an array or one page of a larger result? |
| Outcome | Does the response confirm completion or only acceptance? |
Use the endpoint documentation to answer these questions. One successful sample cannot reveal every optional field or error shape.
Review normal, empty and error examples, then inspect suitably redacted responses from the actual integration if available.
If a required value is absent, stop the dependent action or use a documented lookup; do not guess a substitute. If a list has another page, follow the API's pagination rule before treating the scan as complete.
Once the response is understood, the mapping can specify transformations and destination validation separately.
Before Mapping: Field Meaning Checklist
- Path and typeWhere is the value located? What types are possible (string, number, object)?
- Business meaningIs it an internal ID, customer-facing number, or cross-system reference?
- Presence rulesCan it be absent, `null`, or empty? How should each state be handled?
- Collection typeIs this one item, an array, or a page of results?
- Outcome confirmationDoes the response confirm completion or only acceptance of the request?
