KYC Requests

Part of the IP4CMS portal. ← All module guides

What it's for

KYC Requests is where your team runs identity and "Know Your Customer" verifications through an external verification provider, without leaving the portal. You create a request, give it a reference you'll recognise later, and then run provider actions against it — things like sending a consent request to a customer, running an eKYC or company (CIPC) check, comparing a face to an ID photo, or pulling a workflow's status. Every action's result is saved against the request so anyone with access can come back and see what was done and what came back.

Think of a request as a folder for one verification job. The folder is tied to a channel (your connection to a verification provider), and the channel decides which actions are available inside that folder.

Where to find it

In the portal's left-hand navigation, open KYC Requests. The landing screen is the request list. From there you can open any existing request or start a new one. Channel setup lives separately under Settings → KYC Channels (covered below).

Before you start

A few things must be in place before the module is usable:

• Licence module. Your tenant must be licensed for KYC. Individual provider connections also require their own module — the InTouch provider needs the InTouch KYC module to be enabled on your licence. If a provider's module isn't licensed, you won't be able to configure or use a channel for it, and the system will refuse the channel with a "module required" message.
• Permissions. Access is controlled by four KYC permissions: read (view channels and requests), create, update, and execute (run actions). Viewing the list and creating a request both need the read permission; running any provider action needs the execute permission. Without read you won't see the module at all.
• At least one active channel. A request can't be created until there's an active channel to attach it to. If the New Request screen shows no channels, follow the Set up KYC channels link it offers, which takes you to Settings → KYC Channels.

Key tasks

Configure a KYC channel (provider connection)

Channels are managed under Settings → KYC Channels, not inside the KYC Requests list. A channel is a named, reusable connection to one verification provider, holding the credentials and endpoint URLs that requests will use.

Steps:

1. Go to Settings → KYC Channels and choose to add a channel.
2. Pick the handler (the provider). The list only shows providers your licence allows. Currently the available provider is InTouch ("InTouch Secure Services — Identity verification, consent, workflows, and KYC operations").
3. Give the channel a Code and a Name. The code must be unique within your tenant — you can't have two channels with the same code. The name is what operators see in dropdowns and on the request list.
4. Fill in the provider configuration fields. For InTouch these are: Auth URL (token endpoint), Base URL (consent, upload, service library), Identity URL (organisation identity), Injection URL (workflow initiation), Core URL (workflow status checks), Client ID and Client Secret (OAuth2 credentials), and an optional Organisation Phase Two ID (can instead be fetched via the identity API). All except the Phase Two ID are required — the system rejects the save if a required field is blank.
5. Set Active on and optionally a display order (controls the order channels appear in the New Request dropdown).
6. Save.

Editing a channel re-validates the same way, and the provider must still be licensed. Deleting a channel is a soft delete: historical requests that used it stay intact for audit, so old results aren't lost.

Raise a new KYC request

1. From the KYC Requests list, choose New Request.
2. Pick a Channel from the dropdown. Only active channels appear, ordered by their display order.
3. Enter a Reference (required, up to 100 characters). Use something meaningful — a customer name, account number, or case ID — because this is the main label you'll search and recognise the request by.
4. Save. The request is created in draft status and you're taken straight to its detail screen, ready to run actions.

If no channels are available, the form shows a Set up KYC channels link instead of letting you proceed.

Track and find a request

The KYC Requests list shows every non-deleted request, newest first, with columns for Reference, Channel, Status, and Created date/time. Use the channel filter above the list to narrow to a single channel. Click any row to open its detail.

Statuses you'll see, shown as coloured pills:

• draft (grey) — created, no provider action run yet.
• pending (yellow) — work is in progress.
• completed (green) — finished successfully.
• failed (red) — something went wrong.
• cancelled (grey) — stopped.

Run actions on a request

Open a request to reach its detail screen. The Details tab shows its reference, channel, status and created date. Alongside it is the actions panel, which lists the actions the linked channel's provider supports. Actions are grouped by category and ordered for you.

For InTouch the available actions include:

• Auth — Get Auth Token; Get Organisation Phase Two ID.
• Consent — Send Consent Request (email / SMS / multi-channel link); Consent Status; Consent Request Status; Get Consent Document; Get/By-contact Consent Types; Rerequest Consent; Update Consent Request.
• Workflow — Run Workflow (eKYC, DHA, AML, etc.); Workflow Status; Company KYC (CIPC company check and director information).
• Upload — Upload File(s).
• Service — Identity Document OCR; Face Compare; Passive Liveness.

To run one:

1. Click the action.
2. If it needs input, a parameter form opens. Fields are built from the action's own schema, so they vary by action. For example, Send Consent Request asks for the link type (shortHand: email, SMS, or multi-channel) and a terms link (both required), plus optional email, phone number, callback URL, and retry settings. Company KYC asks for a Reference (required) plus optional company name, registration number, permissible purpose, enquiry reason, and a director list. Workflow Status asks for a tracking ID. Required fields are marked; drop-downs appear where the provider defines a fixed set of choices, and longer free-text/JSON fields get a larger box.
3. Submit. The portal calls the provider, shows a success or error message, and refreshes the available actions.

If an action succeeds, its result is saved against the request and shown immediately. If it fails, you get the provider's error message and nothing is saved for that attempt.

View results

Two places show what came back:

• In the actions panel, the most recent action's result is rendered as a readable summary, sections, or labelled items (depending on what the provider returned), with the raw response available. The result you just ran takes precedence; otherwise the latest saved result for the request is shown.
• The Request Logs tab shows the integration history — the underlying calls made to the provider for this request — useful for troubleshooting when an action errors.

Each saved result records when it was executed, the formatted display, and the raw provider response, so you can always trace a request's history later.

How the data connects

• A KYC channel holds one provider connection (handler + configuration) and belongs to your tenant. Its handler is validated against your licence.
• A KYC request belongs to exactly one channel (its reference is yours; its status moves from draft through pending to completed/failed/cancelled).
• The channel's handler determines the list of actions offered on the request, and how each action's parameter form looks.
• Running an action calls the provider and writes the response into the request's channel output under that action's key, alongside an entry in the integration history (Request Logs). Re-running the same action overwrites that action's stored output with the newest result.
• Channel and request create/update/delete events, and saved action output, are written to the audit log.

Permissions & access

The whole module is gated by the KYC licence module (and provider sub-modules such as InTouch). Within it:

• Read — see KYC Channels and KYC Requests, open a request, and create a request. Without it the module is hidden.
• Create — add a new channel in Settings.
• Update — edit an existing channel.
• Delete — remove (soft-delete) a channel.
• Execute — run any provider action on a request. This is separate from read, so you can let some staff browse requests and results without letting them trigger provider calls.

Tips & gotchas

• No channel, no request. The New Request screen needs at least one active channel; use the in-page Set up KYC channels link if the dropdown is empty.
• Codes must be unique. Two channels can't share a code within your tenant — pick a distinct code per connection.
• Required config is enforced. Saving a channel fails if any required field (everything except Organisation Phase Two ID for InTouch) is left blank.
• Execute is a distinct permission. Read-only users can view requests and past results but cannot run actions.
• Re-running overwrites. Running the same action again replaces that action's stored result; the integration log keeps the full call history.
• Deleting a channel keeps history. Old requests that used a deleted channel still display, so audit trails stay intact.
• Failed actions aren't saved. If a provider call fails you'll see the error, but no result is stored for that attempt — check the Request Logs tab to diagnose.
• Reference is your search key. Choose a meaningful, recognisable reference (max 100 characters) when creating a request.