Mapping Fields

The Mapping step decides what each document contains. The list endpoint finds records; each document is built from the record's detail response, which usually has more fields than the list.

A worked example

The example helpdesk API lists tickets at /v1/tickets (see Choosing records) and returns one ticket at /v1/tickets/{id}:

GET https://api.example.com/v1/tickets/T-1001

{
  "ticket": {
    "id": "T-1001",
    "subject": "Printer offline",
    "status": "open",
    "description": "The second-floor printer has shown Offline since Monday. Restarting it didn't help.",
    "customer": { "plan": "Business" },
    "updated_at": "2026-10-30T14:05:00Z",
    "web_url": "https://help.example.com/tickets/T-1001"
  }
}

Mapping	Value
Record ID	id
Detail Path	/v1/tickets/{id}
Detail Record Path	ticket
Document title	subject
Document text	status labelled Status, customer.plan labelled Plan, description labelled Description
Last updated	updated_at
Source link	web_url

The document is titled Printer offline, links to the ticket, and its text is:

Status: open
Plan: Business
Description: The second-floor printer has shown Offline since Monday. Restarting it didn't help.

The mappings

Record ID

The field that identifies each record, like id. It must be in the list records and in the detail record, as text or a number.

• Every record needs one, and no two records may share it. Setup refuses a mapping where any sampled record has no ID or repeats one.
• The ID is how a record is matched to its document across syncs, so choose a field that never changes.
• It can't be changed after connecting.

Detail Path

The path of one record's detail, with {id} exactly once where the record ID goes, like /v1/tickets/{id}. The ID is URL-encoded, so an ID like A/1 is sent as A%2F1. The detail response must have the same record ID as the one requested.

Detail Record Path

Where the record is inside the detail response: ticket in the example. Leave it empty when the response is the record itself. The value may be an object, or an array holding exactly one object (some CRMs answer { "data": [ {...} ] }); an empty array, or a 204 No Content answer, means the record wasn't found.

Document title

The field shown as the document's name in Documents, like subject. When a record's title is empty, the record ID is used.

Document text

The fields that make up the searchable text, in the order you list them, each with a label (one line, up to 100 characters). Up to 50 fields. Each becomes a line Label: value.

• Fields that are missing, null or empty in a record are left out of its text.
• A field must hold text, a number or true/false. Setup refuses a field that holds a list or an object in a sampled record (map a field inside it instead, like customer.plan). If one appears later, it's left out of that record's text.
• Setup refuses a mapping that gives every sampled record empty text, and warns when only some would be empty.

Last updated (optional)

A field with the time the record last changed, like updated_at. It decides how changed records are found, so it must appear in the list response, not only the detail. Values are ISO 8601 dates, like 2026-10-30T14:05:00Z or 2026-10-30T14:05:00.000+0000. See How changes are detected.

Source link (optional)

A field with a link back to the original record, like web_url. It must be an absolute http or https address; any other value is ignored. When a document is refreshed and its link (or title) has changed, it's processed again even if its text hasn't.

Discover Fields

Discover Fields fetches the detail of one record (the first in the sample page with a usable ID) and suggests fields for each mapping. You can choose a suggestion or type a path yourself.

When you choose Preview, setup fetches the detail of up to three sampled records (matching ones first) and checks the mapping against them:

Check	Result
A sampled record has no ID, a repeated ID, or an ID that isn't text or a number	Error: fix the Record ID
A mapped field holds a list or an object	Error: map a field inside it
Every sampled record would have empty text	Error: add or change text fields
Some sampled records would have empty text	Warning
No sampled record has a value at a mapped path	Warning (you can still type a path the sample doesn't show)
Last updated isn't an ISO 8601 date in some sampled records	Warning
The sample had no records	Warning

Errors must be fixed before you can continue. Warnings let you continue.

Next: Review, start and re-sync.