REST integration — overview
This chapter was written from the product's source code and has not yet been checked by a person on a running Cogneris. If what you see on screen differs, the screen is right — please tell your Cogneris contact so the chapter can be corrected.
The REST integration phase calls a REST API of one of your systems — or of a public service — in the middle of a workflow, and routes the process by the answer. This page explains the parts you configure before the phase itself (Connections), what each tab of the phase is for, the checks that can decide without calling, and walks through the VIES preset end to end.
| Content status | From source; not observed (workflow-fe f88c5c1, workflow-be 6703373, 2026-10-22) |
What it is and when to use it
A REST integration phase is made of two parts that live in different places:
| Part | Where | Holds |
|---|---|---|
| Connection | Administration › Connections, shared by every workflow of your company | The base URL, the authentication and its secrets, default headers, the maximum timeout |
| Phase | The workflow editor, one per call | Which connection, the method and path, how the request is built from the process, how the answer is read, what is published |
The base URL and the credentials live in the connection, never in the phase. The phase stores only a reference to the connection, so a credential is never copied into a workflow, its versions or an export. The phase refuses headers and query parameters that look like credentials (see Request).
Use it to:
- look up a record (customer, supplier, tax number, registry entry) and branch on whether it was found and what it says;
- create or update a record in your system and continue only when it accepted it;
- keep the answer of an external consultation as a fact of the process, with a PDF certificate, so cross-checks and reviewers can use it.
To deliver the final result of a workflow to your system, the Send phase with a webhook is usually enough — see Connect your systems.
Connections
Open Administration › Connections. Reusable base URLs and credentials for REST integrations. Secrets are write-only: once saved they are never shown again.
Everyone who sees Administration can read the list. Only a company administrator sees New connection, Edit and Delete, and can open the form.
The list
| Column | What it shows |
|---|---|
| Name | The connection's name, with a Pre-configured badge when it was created by a connector preset |
| Base URL | The base URL |
| Authentication | None, API key, Basic (user and password), Bearer token or OAuth2 (client credentials) |
| Usage | Not used in any workflow, Used in 1 workflow or Used in … workflows |
| (actions) | Edit and Delete, for administrators |
Loading connections… is shown while the list loads, No connections yet. when there is none. Refresh loads the list again.
The form
New connection opens New connection; Edit opens Edit connection with the stored values.
| Field | What it does | Required | Format / values | Default | Validation messages |
|---|---|---|---|---|---|
| Name | Identifies the connection in the phase's Connection list | Yes | Up to 120 characters, unique in your company | — | Enter a name. · The name can have at most 120 characters. |
| Base URL | The address every call of the phase starts from; the phase adds its Path to it | Yes | Must start with https://, without a user or password in it, and resolve to a public address | https:// | The base URL must start with https:// and have no embedded credentials. |
| Authentication type | How the phase authenticates | Yes | None, API key, Basic (user and password), Bearer token, OAuth2 (client credentials) | None | — |
| API key location | With API key: where the key is sent | Yes | Header or Query string | Header | — |
| Parameter name | With API key: the header or query parameter that carries the key, for example X-API-Key | Yes | Text | — | Enter the parameter name. |
| Username | With Basic | Yes | Text, without : | — | Enter the username. |
| Token URL | With OAuth2: where the access token is requested | Yes | https:// address | https:// | The token URL must start with https://. |
| Client ID | With OAuth2 | Yes | Text | — | Enter the client ID. |
| Scope (optional) | With OAuth2: sent as scope when requesting the token | No | Text | — | — |
| Audience (optional) | With OAuth2: sent as audience when requesting the token | No | Text | — | — |
| Client authentication | With OAuth2: how the client ID and secret are sent to the token URL | Yes | In the request body or HTTP Basic header | In the request body | — |
| API key / Password / Token / Client secret | The secret of the authentication type. Write-only: once saved it shows ••••• set with Replace. Changing the authentication type clears what you typed. | Yes, except with None | Text | — | Enter the secret for this authentication type. |
| Timeout (seconds, 1 to 120) | The longest any call through this connection may wait. A phase may ask for less, never more. | Yes | Whole number 1–120 | 30 | The timeout must be a whole number from 1 to 120. |
| Default headers | Sent with every call. Mark a header as secret to store its value encrypted; secret values are never shown again. Each row has Header name, Value, Secret and Remove; Add header adds a row. A stored secret header shows ••••• set with Replace. | No | Unique names; a secret header needs a value | — | Every header needs a unique name, and secret headers need a value. |
Save (reads Saving… while it works) stores the connection; Cancel closes the form. The service also refuses a name already used by another connection, a host name that cannot be resolved and an address that is not public; the form shows the service's message. Could not save the connection. is shown when the service could not be reached or gave no reason.
Stored secrets never follow a connection to a new destination. When you change the host of the Base URL, the Authentication type, the API key location or Parameter name, or the host of the Token URL, select Replace and enter the secret — and every secret header — again in the same save. As soon as you make such a change the form stops showing ••••• set: it asks for the secret again (The destination changed, so the stored secret no longer applies: type it again.) and for every secret header (The destination changed, so the stored secret headers no longer apply: type them again.). A change of path only, on the same host, keeps them.
Pre-configured connections. A connection created by a connector preset shows Created from a pre-configured connector: the base URL and authentication type are fixed. Timeout, headers and secrets can still be changed. Its Base URL and Authentication type are disabled; a save that changes them is refused with The base URL and authentication type of a pre-configured connection cannot be changed.
Test and delete
- Test connection (only while editing a saved connection; reads Testing…) sends one GET to the base URL with the connection's authentication and shows Connection OK: HTTP … in … ms or Connection test failed: …. It never shows a secret or the response body. Tests are rate limited per company. If the test cannot run at all: The connection test could not be run.
- Delete asks Delete this connection? with Cancel and Delete. A connection used by published workflows is not deleted: This connection is used by published workflows and cannot be deleted. Unpublish or change these workflows first: followed by the workflows, with Dismiss. Other failures: Could not delete the connection.
Loading failures: Could not load the connections. (the list) and Could not load this connection. (opening Edit).
The tabs at a glance
Open the phase on the canvas. The panel has seven tabs; the arrow keys move between them.
| Tab | Answer this question | Details |
|---|---|---|
| Request | Which connection, method and path? Which parameters and headers? How long to wait, how often to retry, which statuses are a success? | Request |
| Schemas | What does the request body look like, what does the answer look like, and what does this phase receive? | Schemas and mapping |
| Request mapping | How is each field of the body filled from the process? | Schemas and mapping |
| Response mapping | Which parts of the answer go into the phase's data, and how are they normalised? | Schemas and mapping |
| Result | Which statuses mean "not found"? Does the body say something the status does not? Should some requests be decided without calling? | Result, Test and Publication |
| Publication | Should the answer become a fact of the process? Should a PDF certificate be stored? | Result, Test and Publication |
| Test | Does it work with a real call? | Result, Test and Publication |
A sensible order for a new integration: create the connection, fill Request, paste the schemas and an input example in Schemas, map the body and the answer, classify the answer in Result, Test, then decide what to publish.
Checks before the call
Checked in order on the request body after the de-para, before calling the destination. The first rule that matches decides and the destination is not called: Success produces the result data below, Not found continues without data, Permanent goes to Error. They sit at the bottom of the Result tab, under Checks before the call.
Use them to avoid calling a service with a request that cannot be valid — an empty identifier, a number with the wrong length — and to record a clear answer instead.
| Field | What it does | Required | Format / values | Default | Validation messages |
|---|---|---|---|---|---|
| Field in the request body | The field the check reads. For POST, PUT and PATCH it is a path in the body built by the Request mapping; for GET and DELETE, the name of a path or query parameter. The fields of the Request schema are suggested. | Yes | Dotted path; [0] for an item of a list, for example items[0].code | — | Check … needs a field in the request body. |
| Operator | How the field is compared. The list shows each operator as a symbol and its name: equals, notequals, gt, gte, lt, lte, in, notin, contains, exists, isempty — the same operators as the Conditional | Yes | One of the list | ∅ isempty | — |
| Value | What the field is compared with. Not shown for exists and isempty. For in and notin: Separate the values with commas. | Yes, for operators that take a value | Text; compared as text, ignoring case, except numbers with numbers | — | Check … needs a value for its operator. |
| Classify as | What a match decides | Yes | Success (without calling), Not found (without calling), Permanent (error) | Success (without calling) | — |
| Result data (JSON object, optional) | Only with Success (Not found continues without data): the answer to record instead of a response — Used as the result instead of the response, for example { "vies": { "status": "invalid", "reason": "malformed" } }. A text value written as {{request.path}} is replaced by that field of the request — by the value itself when the text is only the placeholder, by its text inside a longer text. | No | A JSON object, up to the size the service allows | — | The result data of check … must be a JSON object. |
Checks are numbered Check 1, Check 2… in the order they are evaluated; Move up changes the order, Remove rule deletes one, Add rule adds one. With none: No checks: the call is always made. At most 20 checks are allowed (At most … checks before the call are allowed.).
A Permanent (error) check sends the process to Error with the kind preflight and is never retried. A check that decides Success goes through Publication like any answer.
Tutorial: check a VAT number with the VIES preset
The European Commission's VIES service confirms whether a VAT number (NIF/NIPC) is registered. Cogneris ships it as a connector preset: a REST integration with the connection and every tab already filled in, the same behaviour as the former KYB phase.
1. Add the preset
-
In the workflow editor, find the Pre-configured group, below the phases of the Nodes palette. Its entry is VIES VAT check (EU) with a preset badge; hovering shows its description: Confirms a VAT number (NIF/NIPC) with the European Commission's VIES service and publishes the answer as the kyb_vies document, with a PDF certificate. Same behaviour as the KYB phase.
-
Select it, or drag it onto the canvas. A form titled VIES VAT check (EU) opens. The phase is created only when this form succeeds.
-
Fill in the parameters (required ones are marked with
*):Parameter What it is Required Default VAT number source Where the VAT number is read from. Pick a source from the list or type one: $form.+ the form answer key,$process.+ a process key, or$doc.+ document type +.+ field.Yes $form.nifDefault country The country assumed when the number has no two-letter prefix. Two-letter country code, for example PT. Typed letters become capitals. Yes PTRequester country Your own country, when VIES should record who asked No — but required when Requester VAT number is set — Requester VAT number Your own VAT number, for the same purpose No — but required when Requester country is set — -
Select Add to the flow (it reads Preparing the connector… while it works). Cancel, or Escape, closes the form without adding anything.
Messages of the form: Fill in this parameter., Use a two-letter country code in capitals, for example PT., This source is not valid: use $form.…, $process.… or $doc.….…., and, from the service, The value of "…" was refused. Check it and try again., One of the parameters was refused. Check them and try again., This preset is no longer available. Reload the page to update the list., Could not prepare the connector. Try again in a moment.
The connection. The first time the preset is added in your company, Cogneris creates the connection VIES (European Commission) — base URL https://ec.europa.eu/taxation_customs/vies, authentication None, timeout 20 seconds, marked Pre-configured. Only an administrator can cause that creation; anyone else sees This connector needs a connection that does not exist yet in your organization, and only an administrator can create it. Ask an administrator to add this preset once; after that you can use it. After that, everyone who edits workflows can add the preset, and every VIES phase reuses the same connection. A company that added the preset before version 2 keeps its connection as it is, under its earlier name VIES (Comissão Europeia): the preset finds it by its key, not by its name. Phases added before version 2 keep their settings until the preset is added again.
2. What the preset fills in
The new phase is a normal REST integration with a preset badge on the canvas and, at the top of its panel, the banner Pre-configured connector: VIES VAT check (EU) (version 2) and the button Preset parameters.
| Tab | Filled with |
|---|---|
| Request | Connection VIES (European Commission); Method POST; Path /rest-api/check-vat-number; no path or query parameters, no headers; Timeout (seconds) 20; Retries 5; Wait between retries (seconds) 600; Idempotency-Key off; Success status codes 200; Not found status codes 404 |
| Request mapping | countryCode: the first two letters of the number when it starts with them, in capitals, otherwise the Default country. vatNumber: the number without spaces, punctuation or that prefix. With a requester: requesterMemberStateCode and requesterNumber as fixed values. A helper field malformed, written only when the number cannot be valid: with Default country PT, a Portuguese number — one with the PT prefix or with no prefix — that is not 9 digits; with another default country, a PT-prefixed number that is not 9 digits. |
| Result — checks before the call | Rule 1: vatNumber isempty → Permanent (error): a process without a number goes to Error without calling VIES. Rule 2: malformed exists → Success (without calling), with the result vies.status invalid and vies.reason malformed, echoing the country and number. |
| Result — rules on the body | Not-found status codes (4xx) empty: no status means not found. errorWrappers[0].error in INVALID_INPUT → Success (the number is invalid). INVALID_REQUESTER_INFO → Permanent when a requester is configured, Success otherwise. actionSucceed equals false → Transient. valid isempty → Transient. |
| Response mapping | vies.status (valid, invalid or unknown), vies.countryCode and vies.vatNumber (as sent), vies.name and vies.address (empty or --- become null), vies.nameDisclosed, vies.requestDate, vies.requestIdentifier, vies.requesterAccepted, vies.reason (not_registered when VIES says the number is not valid, or the VIES error code) |
| Publication | Publish the result on, Document type kyb_vies, Display name VIES check, published on Success only. Generate the PDF proof on, Layout VIES (VAT check), File name kyb-vies- followed by the country and the number. |
kyb_vies is the document type the former KYB phase produced, so cross-checks, templates and the review screens that read KYB results read this one too. It is the one published type allowed to have the same name as an existing document type.
3. What you still have to do
- Check the source. Make sure VAT number source names the field where your process really has the number. To change it, select Preset parameters, change the value and select Apply parameters. Applying the parameters again replaces this node's configuration with the preset's. Its connections to other nodes are kept. — any manual change made in the tabs is lost.
- Connect the outputs. Connect Success to the next phase. Connect Error: without it, a process with no number, a refused requester or VIES unavailable after the five retries fails. An HTTP 404 from VIES produces Not found: connect that output if you want such a process to continue on its own path; left unconnected, the process stops there.
- Use the answer. Branch with a Conditional on
restCall.node id.data.vies.status, or compare thekyb_viesfact with the documents in a Cross-check. The certificate is stored with the process documents. - Optionally test. In Schemas, give an Input example that carries the source, for example { "$form": { "nif": "PT500000000" } }, then use Test › Test the call › Call now. The call really reaches VIES.
- Save and publish the workflow.
Expect long waits when VIES is unavailable: a transient answer is retried five times, ten minutes apart.
If the preset catalog cannot be loaded later, the banner shows The preset catalog is not available right now, so its parameters cannot be reopened. The node keeps working as configured. and Preset parameters is disabled. A phase created from a workflow template whose preset parameters were never applied shows VIES VAT check (EU): fill in the parameters to finish this connector. — select Preset parameters and apply them.
Requester refused by VIES
The former KYB phase retried without the requester when VIES refused it. The preset does not: with a requester configured, INVALID_REQUESTER_INFO goes to Error, and its code is in restCall. node id .error.bodyExcerpt. To keep the old behaviour, connect Error to a Conditional that checks that field contains INVALID_REQUESTER_INFO and, when true, to a second VIES phase added without requester parameters.
Related
- REST integration — the phase page
- Request · Schemas and mapping · Result, Test and Publication · Messages
- KYB — converting the former phase to this preset
- Connect your systems
Last reviewed 2026-10-22 · Version 1.0.0 · Owner: product-documentation