No-code: Landing

The Landing integration is the technical implementation associated with a No-Code integration. Once the integration is configured and published on the Facephi IDV Suite platform, Landing is the web channel through which the end user executes the verification Flow.

The integration model is always backend to backend: the client's system generates the session from its server and delivers the end user a single-use access URL. Facephi IDV Suite fully manages the experience from that moment on.

---

Prerequisites

To get a Landing integration up and running, you need:

• A published No-Code integration on the IDV Suite platform.

• The Workflow ID, obtained from the Flows, by accessing the flow you want to use.

• Integration ID, obtained from the Integrations, by accessing the details of the corresponding integration.

• The Tenant ID, visible from the tenant selector at the top of the platform.

• The API Key associated with the integration (available in the Set up step of the configuration).

• The base URL of the API will be provided by Facephi Support or Delivery team.

---

Start a session

The client's backend makes an authenticated call to the IDV Suite API to generate a session. The response includes a single-use access URL (accessUrl) which is delivered to the end user so they can complete the flow.

Onboarding and Authentication Flow

The integration can involve two stages:

1. Onboarding

A verification session is started by generating a accessUrl.

As a result of the process, a unique operation identifier is obtained:

"operationId": "<uuid>"

---

2. Authentication (optional)

In Authentication flows, it is necessary to reuse the result of a previous onboarding.

For this, the operationId obtained in the onboarding must be sent as authenticationId:

"authenticationId": "<operationId obtained in onboarding>"

⚠️ Important The operationId must only be used as authenticationId if the onboarding process was completed and successfully validated.

API Call

Endpoint:

POST https://<base-url>/workflows/{workflowId}/create

Headers:

X-Auth: <API_KEY>
X-Integration-Id: <tenantId>:<integrationId>
Content-Type: application/json

Onboarding Body:

{
    "payload": {
        "source": "<service-id>",
        "customerId": "<string-client-id>",
        "document": { //optional
            "issuer": "<alpha3-issuer-country-code>",
            "type": "<ID_CARD|PASSPORT|DRIVERS_LICENSE|RESIDENCE_PERMIT>",
            "number": "<document-number>",
            "code": "<document-code> (optional)",
            "gender": "<persona-name> (optional)",
            "name": "<person-name> (optional)",
            "surname": "<person-surname> (optional)"
        }
    },
    "timestamp": 1761228742430,
    "signature": "<firma-HMAC-SHA256>"
}

Field descriptions (Onboarding)

Field	Type	Required	Values	Description
payload.source	string	✅	—	Origin service identifier
payload.customerId	string	✅	—	Unique customer identifier
payload.document	object	❌	—	User document information
payload.document.issuer	string	Conditional*	ISO alpha-3 (e.g., ESP, ARG)	Document country code
payload.document.type	string	Conditional*	ID_CARD, PASSPORT, DRIVERS_LICENSE, RESIDENCE_PERMIT	Document type
payload.document.number	string	Conditional*	—	Document number
payload.document.code	string	❌	—	Additional document code
payload.document.gender	string	❌	—	User gender
payload.document.name	string	❌	—	User name
payload.document.surname	string	❌	—	User surname
timestamp	number	✅	epoch (ms)	Timestamp in milliseconds
signature	string	✅	HMAC-SHA256	Payload signature

Notes

⚠️ Conditional fields (payload.document) The object payload.document is optional. However, if it is included in the request, the following fields become mandatory:

• issuer

• type

• number

Onboarding Body:

{
    "payload": {
        "source": "<service-id>",
        "customerId": "<string-client-id>",
        "authenticationId": "<string-authentication-id>"
    },
    "timestamp": 1761228742430,
    "signature": "<firma-HMAC-SHA256>"
}

Field descriptions (Authentication)

Field	Type	Required	Values	Description
payload.source	string	✅	—	Origin service identifier
payload.customerId	string	✅	—	Unique customer identifier
payload.authenticationId	string	✅	UUID	operationId obtained in a successful onboarding
timestamp	number	✅	epoch (ms)	Timestamp in milliseconds
signature	string	✅	HMAC-SHA256	Payload signature

The fields within payload depend on the flow configured on the platform. Check with Facephi Support team which fields are needed for your specific use case. In any case, they are optional.

Request signature

All requests must be signed with HMAC-SHA256 calculated over JSON.stringify(payload). The result is included in the field signature as a hexadecimal string.

TypeScript example:

import { createHmac } from 'crypto';

function getSignature(payload: object, secret: string): string {
  const hmac = createHmac('sha256', secret);
  hmac.update(JSON.stringify(payload));
  return hmac.digest('hex');
}

Successful response

{
  "integrationId": "<tenantId>:<integrationId>",
  "workflowId": "<workflowId>",
  "operationId": "<operationId>",
  "accessUrl": "https://<base-url>/<tenantId>:<integrationId>?ref=<token>"
}

Field descriptions (Response)

Field	Type	Values	Description
integrationId	string	<tenantId>:<integrationId>	Full integration identifier
workflowId	string	UUID	Executed flow identifier
operationId	string	UUID	Unique operation identifier
accessUrl	string	URL	Single-use access URL for the user

Important details

The field accessUrl contains the single-use access URL for that user. This is the URL you should redirect the user to or load in the iframe. Each accessUrl is single-use — the validity time of the URL is 15 min.

The parameter ref included in the accessUrl is a token that contains the operationId and the workflowId needed to resume the operation if the user interrupts the flow.

---

Session behavior

Aspect	Behavior
Duration	The session has a limited duration. If the user does not complete the flow within that time, the operation expires.
When the flow is completed	The user is redirected to the outputUrl configured in the integration (if one was defined).
Single-use	The accessUrl generated with parameters is single-use. OPTIONAL
Retry	If the user needs to resume an interrupted Flow, the resume endpoint allows the session to be recovered using the operationId.

---

Error codes

Code	Identifier	Description
400	INVALID_INTEGRATION_WORKFLOW_PARAMS	Invalid parameters or incorrect format. The detail includes the affected field.
403	INVALID_INTEGRATION_WORKFLOW_ACCESS	The integration does not allow this access mode.
404	WORKFLOW_NOT_FOUND	Flow or integration not found. Verify the Integration ID.
404	OPERATION_NOT_FOUND	The current operation does not exist or does not correspond to the indicated integration.
422	INVALID_INTEGRATION_WORKFLOW_CONFIG	The flow configuration on the platform is not valid. It requires review in the Flow Designer.
429	TOO_MANY_REQUESTS	Request limit exceeded.
500	UNEXPECTED_ERROR	Internal error. Contact the Facephi Support team.
500	REGION_CONFIGURATION_NOT_FOUND	There is no region configuration for the tenant.
500	TRACKING_PLATFORM_NOT_FOUND	There is no tracking platform configuration for the tenant.
500	TRACKING_PLATFORM_CONNECTION_ERROR	Connection error with the configured tracking platform.

---

Do you need more control over the experience?

The Landing integration fully manages the flow UX. If your use case requires native integration into your website or greater control over the interface, see the Web Solution — SDK Web Loader.