Connecting a custom platform and mapping requests and fields
From testing the connection and importing Postman/OpenAPI through assigning request purposes, mapping fields, and activating synchronization.
Reading time: 2 min · Updated 2026-11-21
What this page is for
Defines how Zervixo reads a custom API and which request is responsible for listing, creating, updating, or deleting each data type.
Who can access this
A Company Admin with permission to manage company settings.
Required permission
manage company settings
Field reference
- Request purpose: Defines what the request does, its direction, and when it is used. Example: Products — List with GET imports products, while Products — Update with PUT/PATCH sends a supported update.
- Field mapping: Comes after choosing the purpose and defines how values move inside the request. Example: data.items[*].sku → SKU and data.items[*].price → selling price; it does not by itself decide when the request runs.
- External field path: Where the value lives in the JSON response, such as data.items[*].id.
- Zervixo field: The matching internal field where that value is stored.
Button reference
- Test connection: Checks only the URL and authentication; it does not activate synchronization.
- Save and suggest fields: After choosing the purpose, saves it and analyzes JSON to suggest several mappings; for example, sku → SKU and price → selling price.
- Add a mapping: Manually completes a field missing from suggestions; for example, data.items[*].barcode → product barcode, without changing the purpose.
- Activate connection and sync: Starts synchronization after at least one enabled request is assigned a purpose.
Workflow
- Enter connection details, click Test connection, then create the connection.
- Upload a Postman/OpenAPI file or create requests manually.
- Review every request purpose; list, create, update, and delete are independent operations with separate requests and purposes.
- Test the request to capture a response, then click Save and suggest fields.
- Review suggestions and add missing mappings with Add a mapping.
- Activate the connection and synchronization when the required requests are ready.
Practical scenario
A Postman file contains List Products and Create Order: the system usually recognizes both purposes from their names and suggests product fields when a JSON example exists; the admin reviews suggestions and manually adds missing fields before activation.
Common errors and how to resolve them
- Connection test passed but activation does not work — The test proves only URL reachability and authentication. Assign at least one enabled request to a synchronization purpose first.
- Is mapping fully automatic? — It is suggested automatically when the request name is clear and a response example exists, but purposes and fields must be reviewed before activation.
Frequently asked questions
What is the difference between choosing a request purpose and mapping fields?
The purpose defines what the request does, its direction, and when the system uses it; for example, Products — List with GET imports products. Field mapping defines how values move inside that request; for example, data.items[*].sku to SKU and data.items[*].price to selling price. Correct synchronization needs both.
What is the difference between “Save and suggest fields” and “Add a mapping”?
After choosing the purpose, “Save and suggest fields” saves it and automatically suggests several JSON mappings, such as sku to SKU and price to selling price. “Add a mapping” manually completes one field missed by suggestions, such as data.items[*].barcode to product barcode.
Does mapping List Products also enable create, update, and delete?
No. Every operation has its own request and purpose; only operations you explicitly map are enabled.
Must I map GET, POST, PUT, and DELETE?
No. Start with GET for scheduled imports into Zervixo. Map POST or PUT/PATCH only for supported outbound operations you need. DELETE is not required for basic synchronization and does not run automatically as part of scheduled imports.