Managing Groups

Groups let a merchant organize their verification Flows into named collections. Once a Group exists, its groupId can be referenced elsewhere in your integration to point at a set of Flows instead of a single one — for example, routing different tiers of customers ("Standard Users", "Premium Users") through different verification requirements.

note

A Group is a container for Flows (your onboarding/verification configurations), not for portal team members or roles. Cycurid does not currently expose an API for managing staff accounts, roles, or permissions — that is configured directly in the Merchant Portal.

The same Groups you manage from the Groups page in the Merchant Portal are available through the public API below, so you can manage them programmatically from your own systems (e.g. an internal admin tool, ERP, or CRM) instead of using the dashboard.

Authentication

All endpoints use HTTP Basic Auth with the API key and secret from your merchant account (Company Profile > API Key in the Merchant Portal). See Setup Your Account if you don't have these yet.

Authorization: Basic base64(apiKey:secret)

Your merchant application must be active/approved to use these endpoints — otherwise requests will fail with a 403.

Base URL

https://api.cycurid.com/v2/public/groups

The Group object

{
  "groupId": "b3b3b1de-2f2e-4c2a-9c1a-2a6f2e4d9a11",
  "name": "Premium Users",
  "description": "Enhanced verification for premium tier customers",
  "status": "active",
  "flows": [
    { "flowId": "4b1f6a2c-8e3d-4a11-9c2b-1e6f0a2d3c44", "name": "Enhanced KYC" }
  ],
  "createdAt": "2026-01-15T18:32:00.000Z",
  "updatedAt": "2026-01-15T18:32:00.000Z"
}

Field	Type	Notes
groupId	string (UUID)	Unique identifier, generated by the server.
name	string	1-100 characters. Unique within your account.
description	string | null	Optional, up to 500 characters.
status	"active" | "inactive"	Defaults to "active" on creation.
flows	array of {flowId, name}	The Flows currently in this Group.
createdAt	timestamp
updatedAt	timestamp

List Groups

GET /v2/public/groups

Returns all Groups belonging to your merchant account, most recently created first.

Example

curl -X GET https://api.cycurid.com/v2/public/groups \
  -H "Authorization: Basic $(echo -n 'YOUR_API_KEY:YOUR_SECRET' | base64)"

{
  "groups": [
    {
      "groupId": "b3b3b1de-2f2e-4c2a-9c1a-2a6f2e4d9a11",
      "name": "Premium Users",
      "description": "Enhanced verification for premium tier customers",
      "status": "active",
      "flows": [{ "flowId": "4b1f6a2c-8e3d-4a11-9c2b-1e6f0a2d3c44", "name": "Enhanced KYC" }],
      "createdAt": "2026-01-15T18:32:00.000Z",
      "updatedAt": "2026-01-15T18:32:00.000Z"
    }
  ]
}

Create a Group

POST /v2/public/groups

Field	Type	Required	Notes
name	string	Yes	1-100 characters. Must be unique within your account.
description	string	No	Up to 500 characters.
status	string	No	"active" or "inactive". Defaults to "active".
flowIds	string[]	Yes	At least one Flow ID. Must belong to your account.

Example

curl -X POST https://api.cycurid.com/v2/public/groups \
  -H "Authorization: Basic $(echo -n 'YOUR_API_KEY:YOUR_SECRET' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Premium Users",
        "description": "Enhanced verification for premium tier customers",
        "flowIds": ["4b1f6a2c-8e3d-4a11-9c2b-1e6f0a2d3c44"]
      }'

Returns 201 with the created Group object.

note

Any flowIds that don't belong to your account are silently ignored rather than causing an error. If none of the submitted IDs are valid, the Group is still created with an empty flows list — double-check the Flow IDs you send.

Get a Group

GET /v2/public/groups/:groupId

Returns the Group object, or 404 if it doesn't exist (or doesn't belong to your account).

Update a Group

PUT /v2/public/groups/:groupId

All fields are optional — only send the fields you want to change.

Field	Type	Notes
name	string	1-100 characters. Must remain unique within your account.
description	string | null	Up to 500 characters. Send null to clear it.
status	string	"active" or "inactive".
flowIds	string[]	Replaces the entire Flow list for this Group.

caution

flowIds is a full replacement, not a merge. To add or remove a single Flow, first fetch the Group, edit its flows list client-side, and send the complete resulting array. Omitting flowIds entirely leaves the Group's Flows unchanged. Sending "flowIds": [] removes every Flow from the Group.

Example

curl -X PUT https://api.cycurid.com/v2/public/groups/b3b3b1de-2f2e-4c2a-9c1a-2a6f2e4d9a11 \
  -H "Authorization: Basic $(echo -n 'YOUR_API_KEY:YOUR_SECRET' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
        "status": "inactive",
        "flowIds": ["4b1f6a2c-8e3d-4a11-9c2b-1e6f0a2d3c44", "9a7c2e1b-5f3d-4e21-8b0a-3c1d2e4f5a66"]
      }'

Returns 200 with the updated Group object.

Delete a Group

DELETE /v2/public/groups/:groupId

Permanently deletes the Group. This does not delete the Flows it contained — only the Group itself and its association to those Flows.

curl -X DELETE https://api.cycurid.com/v2/public/groups/b3b3b1de-2f2e-4c2a-9c1a-2a6f2e4d9a11 \
  -H "Authorization: Basic $(echo -n 'YOUR_API_KEY:YOUR_SECRET' | base64)"

Returns 200:

{ "message": "Group deleted successfully" }

Errors

Status	Meaning
400	Request body/params failed validation. The response includes an errors array describing each issue.
401	Missing or malformed Authorization header.
400	Invalid API key/secret combination.
403	Merchant application is not completed or approved.
404	Group not found (wrong groupId, or it belongs to another account).
409	A Group with that name already exists on your account.

Notes

• Group names are unique per merchant account, not globally — two different merchants can each have a Group named "Premium Users".
• There is no default/system Group — every Group is created explicitly and can be deleted at any time.
• Your subscription plan may limit the total number of Groups you can create.