Changelog

KYC

Organization KYC warning policy can force in review or rejected per code

Per-code KYC warning policy

In organization settings, each document-check warning code can do not intervene, force in review, or force rejected. The heaviest status wins; a code with no rule keeps the document-check result. The adjustment is audited on metadata.kycWarningEscalation.See KYC warning risk codes.

APIKYCBiometrics

KYC and biometric sessions can use an explicit or organization-default UI language

Configurable validation language

POST /api/kyc/validations now accepts the optional language field, matching biometric session creation. A request-level language takes precedence over the organization’s default; when neither is set, the hosted UI keeps device language detection.See Create KYC Validation and Embedded Biometric Session.

APIOnboarding

New configurable reminder, closure, and reactivation lifecycle for onboarding

Secure onboarding reactivation

Document requests can use automatic reminders and an operator-approved final closure. The Continue onboarding link records intent and runs the analysis again without directly reactivating the entity.View the reactivation endpoint.

APIRisk matricesData listsWebhooks

Parent organizations can share live risk matrices, data lists, and webhooks with direct child channels

Holdings can explicitly select which direct child organizations in the same environment receive each risk matrix, tenant data list, or webhook. A selected child sees the same UUID (and the same list items or webhook secret). Catalog fields: origin (local | parent), readOnly, sharedEnabled. Assigning or running a parent matrix, and dispatching a parent webhook, require the channel opt-in (POST /risk-matrices/{id}/child-share, POST /data-lists/{id}/child-share, and POST /webhook-config/{id}/child-share). Writes on a parent row return 403 SHARED_RESOURCE_READ_ONLY. Webhook payloads keep organizationId of the channel. See List risk matrices, List data lists, and Webhook configuration.

APITransactionsInvestigations

Transactions can now be reported manually under an investigation category

Manual transaction risk reports

Analysts can use Report Transaction Risk to classify a transaction under an active category such as Fraud or AML. Gu1 creates a rule-less alert; the analyst chooses to create an investigation or consolidate into a compatible one for the selected subject. The decision is audited, the reason is optional, the financial status remains unchanged, and no risk analysis audit is fabricated. The transaction keeps alert and investigation IDs, blocks duplicate reports, and links back to the case.

APIServicesArgentina

Holder intelligence accounts-count returns CUIT demographics estimates

CUIT demographics on accounts-count

Accounts count now includes an additive cuitDemographics object (age cohort, probable foreigner, inferred gender / contributor type). Values are computed at response time from CUIT digits — low confidence; not proof of age or nationality. Existing account totals and rule paths under services.holder_intelligence.* are unchanged.Rule Builder also adds tax_id_demographics_matches on CUIT fields: one configurator can combine age range (overlap or fully contained) and probable foreigner (medium or high confidence). It is evaluated locally, does not query or charge Holder Intelligence, and does not change existing tax_id_age_* operators. Holder Intelligence templates expose this as an optional preconfiguration filter; when left empty, their original conditions remain unchanged.

APIEntitiesBrazil

Brazilian automatic company creation now returns the main CNAE

Main CNAE in Brazilian company profiles

Automatic entity creation now copies the normalized main economic activity into entityData.company.cnae, cnaeDescription, and the compatible industry description. Integrators no longer need an additional enrichment read to obtain the main CNAE after company creation.

APIEntitiesEnrichment

Read persisted enrichment: normalized dossier and current mapped/raw

GET normalized enrichment and current enrichment data

Two read endpoints are now documented with the persisted enrichments (they already existed; this is documentation, not a new contract):

Get normalized enrichment — GET /entities/{id}/normalized-enrichment. Gu1 NormalizeType dossier (RootData + consolidators + summaries). 404 NOT_FOUND if the entity has no normalized row yet.
Get current enrichment data — GET /entities/{id}/enrichment-data. Last mapped / raw payloads keyed by integration code. If the entity exists but has no snapshot, HTTP 200 with hasEnrichmentData: false.

Neither call re-runs integrations or consumes enrichment credits. Get entity still does not replace these responses. Permission: entities:read.

APIServicesRules

Operation statuses on the CPF in-list checks

`statusIds` on the CPF in-list checks

CPF membership checks now return the operation statuses alongside count and the amounts:

CUIT in-list: statusIds, asRecipientStatusIds, asInitiatorStatusIds.
Account in-list: statusIds.

These are the unique, non-empty, sorted statuses across all matching operations: 1 (case filed), 2 (case confirmed as fraud), 3 (genuine transaction). They are computed in the same pass as the COUNT, so expected cost and latency are unchanged. With availableCount=false they arrive as null, just like count.The fields are additive: an integrator sending yesterday’s request gets the same response plus these keys.In rules, services.cpf.status_ids (and its per-role and per-account variants) no longer requires the full lookup: it resolves from the same in-list as count.On top of that, the membership conditions (services.cpf.in_list, services.cpf.hit, services.cpf.cbu.in_list, services.cpf.cvu.in_list, services.cpf.account.in_list, services.cpf.account.hit) accept the optional serviceCpfStatusIds modifier in the condition body:

{
  "field": "services.cpf.in_list",
  "operator": "eq",
  "value": true,
  "serviceCuitFieldPath": "destinationTaxId",
  "serviceCpfMode": "both",
  "serviceCpfStatusIds": ["2"]
}

The condition matches only when the CPF appearance has at least one operation in one of those statuses, with a single service call and no second condition. Empty or absent means any status, and a negative check (value: false) is never narrowed. It is additive: an existing rule without the field behaves the same.

APIEntities

Automatic entity creation errors are English

Integrator-facing `error` strings

On automatic entity creation (sync, proxy/webhook, and creationFailed[]), the error field is always English. Use code (for example UPSTREAM_CREDITS_ERROR, DOCUMENT_RESTRICTED, INVALID_TAX_ID) for branching. The dashboard still localizes the same codes for operators.When basic-data fails and the entity is not created, enrichmentFailed stays [] (that array is only for extra enrichments on a persisted entity). The additive field enrichmentFailedDetails lists each attempt (primary + fallbacks) with providerCode, code, and errorMessage. The same list is nested on the creationFailed[] row.Gu1 can now explicitly enable minor creation with a provisional Person <taxId> name. When the primary source identifies a minor, the entity is immediately created with attributes.isMinor: true, without retries, fallbacks, or additional enrichments. Risk analysis runs normally. The setting is off by default.

APIEntities

Entity accounts CRUD by externalId and taxId

Account routes by external ID and tax ID

GET/POST /entities/{id}/accounts and PATCH/DELETE /entities/{id}/accounts/{accountId} still use the Gu1 entity UUID. The same operations are available as:

/entities/by-external-id/{externalId}/accounts
/entities/by-tax-id/{taxId}/accounts

(plus /{accountId} on PATCH/DELETE). {accountId} remains the Gu1 account UUID. Tax ID lookup strips punctuation and is case-insensitive (same alphanumeric key as org-level tax uniqueness). See Entity accounts.

APIEntities

Spain company taxId accepts NIF and NIE besides CIF

Spain KYB tax IDs (autónomos)

For countryCode: ES and type: company, taxId now accepts NIF (8 digits + letter, e.g. 74387028Z) and NIE (X/Y/Z + 7 digits + letter) in addition to CIF. Sole traders were previously rejected with INVALID_TAX_ID / “Invalid CIF format”.See Country requirements and Tax ID formats.

APIEntitiesDashboard

Entity accounts

Person and company entities can now hold multiple financial accounts in currencies such as USD, ARS, and BRL. The new CRUD endpoints support client account IDs, account status, CBU/CVU, IBAN, generic account numbers, aliases, and a primary account per currency. The dashboard includes an Accounts tab, country and account-type selectors, and translated account events in the timeline.accountType is now a canonical enum covering bank, savings, checking, wallet, payment, investment, credit, and institutional accounts. POST and PATCH return 400 VALIDATION_ERROR for unknown values. Historical values outside the enum are retained in metadata.legacyAccountType and normalized to other.See Entity accounts.

APIAuth

429 rate limit message includes minutes until reset

Rate limit wait in the 429 body

When an API key exceeds its quota, message includes how many minutes remain (e.g. Try again in 17 minutes.). The JSON also adds retryAfterMinutes (ceil of retryAfter seconds). retryAfter and Retry-After are still in seconds. The window still starts at the first request of the cycle, not at clock-hour boundaries.See Authentication.

Bulk importsEntitiesAPI

Entity bulk: when basic data fails vs extra enrichments

Automatic vs manual entity rows

Import entities now documents that automatic is the same pipeline as Create entity automatically: if the basic-data step fails, the row is not created and the job continues (unless stopOnFirstError). Extra enrichments that fail after a successful basic-data step do not roll back the entity. manual still creates from suggested_name first; optional enrichment failures leave the entity in place.See also Bulk imports overview.

Bulk importsEntitiesTransactionsAPI

Entity bulk cap 20k, one live job per org, global slots

Batch import concurrency and entity row cap

Entity CSV imports are capped at 20,000 rows per request (plan limits still apply below that; BULK_AUTOMATIC_ENTITY_MAX_ITEMS can only lower the cap). Transaction files stay at up to 5 × 100,000.Each organization may have one live job (queued or running) per import type. A second POST of the same type returns 409 JOB_IN_PROGRESS with jobId. At most one job may wait (queued) per organization: if a job of either type is already queued, POST of the other type returns 409 JOB_ALREADY_WAITING. Transactions and entities cannot run at the same time in one organization: a POST of the other type returns 202 queued with code: "QUEUED_WAITING_PREVIOUS_JOB" and queue.waitingForOrgJob: true only when the other type is running and nothing is already waiting. It starts when the current job finishes. At most two organizations process the same type at once; additional orgs receive 202 with code: "QUEUED_WAITING_SLOT" and queue: { globalSlots, running, waitingAhead, waitingForOrgJob } — never 409 for the global cap.The 202 body includes code (QUEUED_WAITING_PREVIOUS_JOB or QUEUED_WAITING_SLOT) and message. The same reason is stored on the job row as metadata.queueWaitReason (previous_job or global_slot) so import history can show it while status stays queued. It is not a field on the 202 JSON itself.Transaction jobs remain running until queued rule evaluation finishes when executeRules is true. User-event imports are unchanged.See Bulk imports overview and Import entities.

ExportsEntitiesTransactionsAPI

Entity and transaction export files no longer expire

Per-file retention in export history

Export job responses now include nullable fileExpiresAt. A null value means the stored file has no expiration; linkExpiresAt still only describes the signed email link.New entity and transaction exports remain available in history without expiration. Other export kinds keep their existing retention period, and existing files keep their previous expiration. See Bulk entity export and Report export jobs.

Bulk importsRisk matrixAPI

Post-import matrix over a previous entity batch

postImportActions.run_risk_matrix_filtered now accepts sourceImportJobId. After the current file completes, Gu1 can run the matrix on created entities from a selected previous import, including entities without a relationship in the current file. The previous batch is validated within the same organization and must have its full report available.The new onlyWithoutRiskMatrixExecution=true scope runs the matrix on every entity of the selected type without a recorded matrix execution. Once processed, those entities are not selected by later imports.This is an optional additive field and cannot be combined with relatedEntitiesOfCreatedEntitiesOnly=true. See Import entities.

DevicesInvestigationsAPI

Device context for investigations

Devices for an entity and its direct relationships

The new GET /devices/entity/{entityId}/investigation-context endpoint returns devices grouped by entity for investigation views. Set includeRelatedEntities=true to include active direct relationships in either direction; the default remains the investigated entity only.This is an additive endpoint. Existing device listing requests are unchanged. See List devices for an entity.

Bulk importsAPI

New bulk import job failure codes

`jobFailure.code`: `ARTIFACT_UPLOAD_FAILED` and `QUEUE_ERROR`

When a batch was registered but died before starting — either because its payload/source file could not be stored, or because the queue rejected the enqueue — the job ended as failed with jobFailure.code: "WORKER_ERROR", and the actual reason only lived in the free-text message. Those two cases now have their own codes:

ARTIFACT_UPLOAD_FAILED — the payload or source file could not be stored, so the worker had nothing to resume from.
QUEUE_ERROR — the queue rejected the enqueue and the job never started.

In both cases no rows were imported and the upload should be retried. The codes show up in jobFailure.code on job status and failures (JSON), and match the error.code the import POST already returned.Additive change: if you switch on jobFailure.code, these values previously arrived as WORKER_ERROR. Existing jobs are not rewritten.See Batch import failure codes.

Bulk importsAPI

Richer transaction warnings in validate-csv

`validate-csv`: row-level warnings for transaction mappings

The preflight for transaction mappings now reads the whole file (up to 50,000 data rows) instead of the first 50, and checks the closed value sets of type, status, paymentMethod and reason — previously an unmapped enum only surfaced once the import job was already running.Additive changes to the 200 response, no breaking change:

New top-level totalRows alongside the existing sampledRows.
Each entry of warnings may now carry field, value, allowedValues and occurrences. Existing code, message, row and column are unchanged.
New warning code INVALID_ENUM_VALUE. Handle unknown codes by falling back to message.
Warnings are grouped by problem instead of emitted per row: one entry reports the first affected row plus occurrences. If you counted warnings.length as “bad rows”, read occurrences instead.

ok stays true for transaction mappings and the import is still allowed. Nothing changes in what gets imported.See Validate CSV.

EntitiesAPI

New entity status awaiting_information

New entity status: `awaiting_information`

Person/company entities accept a new lifecycle value awaiting_information (waiting on client data — typically documents requested during onboarding). It is not pending_verification (identity KYC/KYB still outstanding).

You may send status: "awaiting_information" on create or PATCH like any other lifecycle value.
The onboarding analyst sets this status when it sends the merchant document-request email, storing the previous status on the request. After the merchant submits the documents (or the operator accepts/discards intake), Gu1 restores that previous status — unless an operator changed or locked status while waiting.
awaiting_information does not block operations the way blocked / suspended / rejected do.

See Entities overview — Entity Status.

ServicesAPI

Marketplace service: Fraud Prevention Center (CPF)

Marketplace service: Central de Prevención de Fraude (CPF)

New integration code ar_gueno_cpf_service. Gu1 proxies CPF lookups (CUIT + recipient CBU/CVU) including cheap in-list checks, full lookups, batches, and operation detail.

Base path: /api/integration-services/ar_gueno_cpf_service
Rules: services.cpf.* (CUIT via serviceCuitFieldPath)
In-list (availableCount=true): also returns accumulated amounts (totalAmount, role amounts)
Distinct from BCRA Central de Deudores enrichment

See Fraud Prevention Center (CPF).

EntitiesAPI

Entity report: auditable manual risk and normalized AML screening

Entity report: explicit current risk and AML screening

GET /entities/{id}/export-data adds two objects and changes the meaning of checks[]. The PDF (dashboard download, POST /entities/{id}/export and the email delivery) reflects the same data.

riskSummary (new): the risk the report presents as current. mode is manual, automatic or not_evaluated. When a manual override is active, effective carries the manual score, manual includes justification, user, date and previous score, and automatic.supersededByManual flags the matrix score as historical. Previously the report showed the matrix score even when the operator had set the risk by hand.
amlScreening (new): one row per watchlist data source with matchStatus, totalHits / relevantHits, listNames, reportedRiskLevel (raw value as received, including unknown when that is what was returned) and effectiveRiskLevel + riskLevelSource (level derived from matches when needed internally). The PDF shows reportedRiskLevel when present.
checks[]: adds screeningType, executionStatus (completed / failed), matchStatus and optional effectiveRiskLevel. matchStatus can be undetermined: a check without normalized screening is no longer presented as “No Match”.
Integrator impact: the fields are additive and existing ones are unchanged. If you inferred “no matches” from checks[], read amlScreening or checks[].matchStatus and treat undetermined as inconclusive.

See Entity PDF report by email.

TransactionsAPI

destinationDetails.mcc accepts 3 or 4 digits

Transactions: MCC length relaxed

destinationDetails.mcc on transaction create now accepts 3 or 4 characters (previously exactly 4). Integrators may send values such as "742" or "0742". Preferred form remains the ISO 18245 4-digit string when available.See Create transaction.

AML CryptoAPI

AML Crypto API parity (checkId + history)

AML Crypto: client-flow parity

Gu1 AML Crypto (/api/aml-crypto) now matches the product flow for wallet/transaction screening:

Execute endpoints return { success, data } with optional checkId when a history snapshot is stored.
GET /aml-crypto/checks supports filters + pagination (total, limit, offset).
GET /aml-crypto/checks/:id returns a single org-scoped check.
Permissions: aml_crypto:read (history) and aml_crypto:execute (lookups).

See AML Crypto overview.

WorkflowsAPI

Templates always create disabled automations

`POST /automations/from-template` always creates disabled

Automations created from a template are now always persisted with enabled: false, regardless of the enabled value in the template definition. Previously most catalog templates were created active and could fire on the next matching event before you reviewed recipients, risk matrix, or filters.

Impact for integrators: after from-template, activate explicitly with POST /automations/:id/toggle.
No request/response fields changed.

See List templates.

WorkflowsAPI

Entity monitoring automation template

Automation template: entity monitoring (scheduled)

New system template entity_monitoring_scheduled: cron → fetch_entities (preconfigurable filters) → run_risk_matrix (chosen matrix). Created disabled.
Preconfig knobs: schedule frequency/time/timezone, entity filter builder, fetch limit, riskMatrixId.

See List templates.

WorkflowsAPI

Automation templates preconfig + alert→email

Automation templates: preconfig params + alert → email

GET /automations/templates may include parameterDefinitions (path + optional mirrorPaths) for catalog knobs.
POST /automations/from-template accepts optional paramValues. Required params return 400 when missing.
New system template alert_created_email_notify: on alert_created, send email via send_push_notification (configure rules, severities, recipients, message template). Created disabled.

See List templates.

ReportsAPI

Editable presets, preview, and CSV/PDF

Editable presets + preview + CSV/PDF

Report presets are now updatable via PATCH /report-presets/:id (name, description, params; templateCode fixed). POST /report-templates/:code/preview returns sample CSV/PDF, and the catalog supports CSV/PDF on bulk templates and alerts_by_rules. See Presets and Templates.

ReportsWorkflowsAPI

Report generate is async (S3 + Descargables)

Report generate → async S3 + Descargables

Generate (template or preset run) always queues a background export to object storage and returns 202 with jobId. Download from Reporting Descargables via Report export jobs (GET /report-export-jobs).

alerts_by_rules no longer returns a sync XLSX or contentBase64 in the run response.
Automation send_report / Generar reporte prefers reportPresetId; set optional sendEmail (+ recipientEmails) to also email the file.
Investigations, entity PDF profile, and Metrics Hub with delivery: "download" no longer return skipped for missing recipients: they queue the job and the file lands in Descargables. Profile and metrics reports are listed as kind: "documents".

See Report templates, Report presets, and Report export jobs.

ReportsAPI

Org-scoped immutable report presets

Report presets API

Organizations can save frozen Gu1 template configs via GET/POST /report-presets, GET/DELETE /report-presets/:id, and POST /report-presets/:id/run. Presets are immutable after create (delete only), capped at 50 per org, and power one-click download plus scheduled send_report automations. See Report presets.

ReportsWorkflowsAPI

Operational report templates and alerts-by-rules export

Report templates API

Gu1 now exposes GET /report-templates, GET /report-templates/:code, and POST /report-templates/:code/run. Reports for alerts, entities, transactions, and investigations expose field → operator → value conditions, including Tax ID custom-list membership, age, PEP, sanctions, adverse media, MEI, and criminal legal proceedings. Conditions can be frozen in org presets. Ambiguous portfolio/holder-variation templates are not part of the catalog. See Report templates.

WorkflowsInvestigations

investigation_status_changed now covers every transition and exposes the previous status

Automations on investigation status change

The investigation_status_changed trigger is now emitted on every case status transition, not only when the status is changed through the API.

New origins that trigger automations: moving forward or back a stage (In progress ↔ Pending review and close by stage), reopening a closed case, agent actions, the change_status / start_investigation action of another automation, and the automated resolution pipeline. None of these emitted the event before, so automations on PENDING_REVIEW never ran.
No longer emitted when the status does not change: resending the current status (for example CLOSED on an already closed case) no longer produces duplicate notifications.
Previous status in the context: new condition investigation.previousStatus and new template variable {{investigation.previousStatus}}, plus investigation.transitionSource to know where the change came from.
New system email templates per status: investigation_in_progress_email_*, investigation_pending_review_email_*, investigation_closed_email_* and investigation_reopened_email_* (es / en / pt).
The status picker in conditions now offers the four real statuses of the flow, including Pending review.

Details: Triggers.

If you already had automations on this trigger, they may now run on transitions that previously went unnoticed. Review your status conditions before enabling customer-facing notifications.

EntitiesAPI

Entity status not_started + clearer status docs

New entity status: `not_started`

Person/company entities accept a new lifecycle value not_started (V2 NOT_STARTED equivalent).

Default on create stays under_review for existing integrations.
Pass status: "not_started" on create (manual, automatic, or bulk) to opt in.
Risk matrix labels and updateEntityStatus rules can move from not_started to under_review, active, rejected, blocked, etc. — there is no mandatory intermediate step.
Full table and example flows: Entities overview — Entity Status.

ServicesAPIRules

Holder intelligence metrics: total delta and % change

Total CBU+CVU delta and percent change on metrics

GET /integration-services/ar_gueno_holder_intelligence_service/cuits/:cuit/metrics now exposes derived totals on data.metrics:

totalDelta — cbuDelta + cvuDelta
totalPctChange — % change over combined start stock (null when start = 0)
totalAccountsStart / totalAccountsEnd — CBU+CVU stock at window bounds

Rules engine paths: services.holder_intelligence.metrics.total_delta, total_pct_change. Existing channel fields are unchanged.

EntitiesAPI

Enrichments outside the entity country are skipped

`autoExecuteIntegrations.enrichments` is filtered by country and entity type

When creating an entity (manual or automatic), enrichment codes whose catalog entry does not cover the entity countryCode (or GLOBAL) and type are now ignored instead of being executed. An Argentine tax-registry enrichment can never resolve a Brazilian CNPJ, so the call only produced a guaranteed failure in the entity audit trail.

Applies to enrichments, enrichmentGroupRefs and executeAllActiveEnrichments on both the main entity and related entities (autoExecuteIntegrationsShareholders).
Org enablement, integration blocks and fallback chains are unchanged: only country / entity-type coverage is checked here.
Impact: requests that mixed codes from another country stop returning those providers under enrichment errors. Any provider valid for the entity country behaves exactly as before.

EntitiesAPIDashboard

Manual entity notes via API + UI

Create notes on an entity dossier

Operators can now add multiple notes on a person/company entity from the Entity Builder notes dialog (not only via contextual-agent HITL).

POST /entities/{id}/notes — body: content (required, max 8000), optional noteType (general | analysis | finding | recommendation), optional isImportant (boolean). Requires entities:edit (legacy entities:write).
Each note stores source: manual (UI) or agent (HITL / contextual agent).
Audit timeline event note_added records source, noteType, noteId, and content.
GET /entities/{id}/notes is unchanged (list, newest first).

Impact: clients can document decisions without opening an agent flow; existing HITL-created notes keep source=agent (legacy agent_contextual rows are renamed by migration).

TransactionsBatchAPI

Transaction batch rejects spreadsheet-rounded ids

New row failure code: `SCIENTIFIC_NOTATION_ID`

Transaction batch rows are now rejected when an id field arrives in scientific notation (e.g. 5,04E+13), which happens when a CSV with long numeric ids (CPF, CNPJ, account numbers) is opened and re-saved in Excel or Google Sheets. Only three significant digits survive the rounding, so the id cannot be recovered and silently breaks any rule that groups by it.

Checked fields: externalId, originExternalId, destinationExternalId, originTaxId, destinationTaxId.
The row fails with code SCIENTIFIC_NOTATION_ID in failures.csv / JSON failures[]; identifier_type lists the offending fields.
Behaviour follows batchErrorHandling like any other row failure (rollback_all aborts the file, continue_collect_errors creates the valid rows).
Impact: files that used to import with corrupted ids now report those rows as failures. Re-export the CSV keeping id columns as text.

See Batch import failure codes.

TransactionsBatchAPI

Transaction batch: skip invalid entity refs + failures.csv in S3

Row error policy and S3 artifacts for transaction batch

batchErrorHandling=rollback_all is the default (UI + multipart upload when omitted): aborts the file on invalid refs/amounts or insert failures; detail goes to failures.csv (S3), without giant jsonb arrays.
Clients can choose continue_collect_errors (skip invalid rows and create valid ones) or stop_keep_success.
The error-policy selector is also available on non-mapper imports (transactions and entities).
Failures CSV columns: external_id,code,error,role,identifier_type,value.
New GET /batch-import/jobs/{jobId}/payload: download the processed payload.json when stored (authenticated attachment).
Alignment: user-event and entity batch jobs now follow the same S3-first failures model as transactions (item_failures / terminal item_results cleared; JSON samples hydrate from CSV). Entity kind in responses is entity_batch; entity_automatic remains an accepted input alias.

See Batch import failure codes, Transaction batch failures, and Download batch job payload.

TransactionsRules

Filter transactions by their latest rules evaluation date

Latest rules evaluation date filter

GET /transactions now accepts the optional inclusive ISO timestamp filters lastRiskEvaluationFrom and lastRiskEvaluationTo. They can be combined to select transactions whose latest successful rules evaluation falls within a date range. Transactions evaluated before this field existed are matched using their risk analysis history, and list items now return lastRiskEvaluationAt.See List transactions.

WebhooksEntities

Legacy entity webhooks now include score and document number

Additional fields in legacy flat entity webhooks

Legacy flat entity webhook payloads now include the additive fields riskScore and documentNumber. Existing status values and mappings remain unchanged.See Entity webhook events.

TransactionsBatch

Download which transactions were skipped as duplicates

Skipped rows report for transaction batches

New endpoint GET /batch-import/transaction-jobs/{jobId}/skips.csv lists the transactions a batch did not insert because the externalId already existed (columns external_id,reason). Until now skipped was only a counter, which made a duplicate re-upload look like a silent failure.

Available for jobs run with the default skipDuplicates=true; with skipDuplicates=false duplicates are resolved by the database and only counted, so the endpoint returns SKIPS_NOT_AVAILABLE.
Jobs finished before this release have no stored report (SKIPS_NOT_AVAILABLE).
Also available as a download button in the bulk imports history.

See Transaction batch failures.

EntitiesBatch

Bulk: apply declared relationships when entity already exists

Declared relationships on duplicate `tax_id` (bulk)

In manual bulk import, when a row’s tax_id already exists and creation is skipped, Gu1 still applies that row’s declared relationships / CSV related_* columns (same as automatic create). Existing edges (same source → target + type) are skipped idempotently.See Import entities (bulk).

EntitiesAPIBatch

Declarative relationships on entity create + bulk import

Link to existing entities on create and bulk import

You can declare relationships to entities that already exist (relatedEntityId / relatedTaxId / relatedExternalId + relationshipType + role) without relying on enrichment depth:

POST /entities and POST /entities/automatic: optional relationships[] body (max 10).
Platform bulk CSV: columns related_tax_id / related_external_id / related_entity_id, relationship_type, relationship_role, relationship_as_source (one relationship per row).
Missing counterpart → RELATED_ENTITY_NOT_FOUND and the entity is not created.

See Create entity, Create automatically, and Import entities (bulk).

WebhooksSecurityIAM

Security webhook: environment access changed

`security.member.environment_changed`

When an admin updates a member’s production/sandbox access from Teams (roster) in one assignment, Gu1 emits a single webhook instead of multiple grant/revoke events:

Event: security.member.environment_changed
context.fromAccess / context.toAccess: "both" | "production" | "sandbox" | "none"
changes.environmentAccess: { previous, current } with the same values

Existing security.member.environment_granted / .environment_revoked remain for single-environment grant/revoke flows.See Security webhook events.

TransactionsAPIBatch

linkEntityStrict + soft-link without breaking batch defaults

Entity link: soft-link always, strict default unchanged for batch

Transaction create / batch always tries to auto-link when a match exists (entityId → externalId → taxId).

Batch default (BC): omitting flags stays strict — validateExistingEntity still defaults to true. Unresolved refs → 400 INVALID_ENTITY_REFERENCES (same as before for clients that omit the field).
linkEntityStrict=true: force hard-fail (body or query).
linkEntityStrict=false: force soft-link (do not fail if missing), even if validateExistingEntity would otherwise be true.
validateExistingEntity=false: soft-link (and still attaches when found — previously soft mode skipped linking on batch).

Single POST /transactions keeps validateExistingEntity default false.See Create batch.

APIBilling

Creation contract quota error code rename

Error code: `CREATION_CONTRACT_QUOTA_EXCEEDED`

When an organization contract creation quota is exhausted (entities, transactions, user events), Gu1 APIs now return 429 with code CREATION_CONTRACT_QUOTA_EXCEEDED (replacing CREATION_QUOTA_EXCEEDED).

Same HTTP status and payload shape (module, remainingTotal, periodKey, requested).
Batch import row failures emit CREATION_CONTRACT_QUOTA_EXCEEDED; the old code remains accepted as a deprecated alias for historical failures.csv.

See Batch import failure codes.

APIEntities

Entity taxId uniqueness across person and company

Tax ID uniqueness (org-wide)

An active taxId (normalized alphanumeric) may belong to only one entity per organization, whether person or company.

Same type already exists → automatic creation reuses that entity (alreadyExisted).
Other type already holds the tax ID → 409 with code DUPLICATE_TAX_ID (no new row).
Applies to manual create, automatic create, tax ID PATCH, and soft-delete restore.
Historical duplicate rows are not deleted; new conflicting writes are blocked in app and via a database trigger.

See Create entity automatically and Create entity.

APIRules

addFieldToCustomList rule action

New rule action: `addFieldToCustomList`

Transaction, person, and company rules may include addFieldToCustomList. On match, the engine extracts one or more fields from the evaluation context and appends them to tenant custom lists (type: custom, active, non-global).

{
  "type": "addFieldToCustomList",
  "addFieldToCustomList": {
    "mappings": [
      { "fieldPath": "originTaxId", "listId": "uuid-list-123" },
      { "fieldPath": "metadata.phone", "listId": "uuid-list-456" }
    ],
    "reason": "Optional item reason"
  }
}

Empty values are skipped; duplicate primaryValue entries are ignored. Available on universal rule POST/PUT and in the Rule Builder.

APIEntities

Entity creation list enforcement

Creation blocklist (risk analysis settings)

Organizations can configure creation blocklist rules in Organization settings → Risk analysis: map an entity field (e.g. taxId) to a custom list. If the value is found in the list, entity creation is blocked: the request fails with 422 and error code ENTITY_CREATION_LIST_BLOCK (details include ruleId, listId, fieldPath, scope, matchedValue). The blocked attempt is recorded in the audit log as evidence.Applies to POST /entities, POST /entities/automatic, bulk import, upsert create path, and SDK auto-entity creation. Shareholder/UBO checks run during automatic creation when scope is configured; if a shareholder is blocked, the entities created in that automatic run are rolled back.

APIEntities

PATCH /entities/{id}/attributes

Dedicated attributes update endpoint

PATCH /entities/{id}/attributes — update only custom attributes without touching other entity fields.

mode: merge (default) — sent keys overwrite or create; omitted keys are kept
mode: replace — body attributes becomes the full map ({} clears all)
Nested category buckets supported on write (same as entity update)
Triggers entity.updated webhook and risk matrices with entity_updated trigger when configured

See Update entity attributes.

APIEntities

Entity attributes: verbatim storage + categories

Custom attributes stored verbatim (API)

Additive. attributes are stored exactly as sent on create/update/upsert/automatic import paths — nested input is no longer flattened.

Uncategorized: scalar/array values at the root (e.g. { "phone": "..." }) — unchanged.
Categorized: a top-level object groups its inner keys under that category (e.g. { "contact": { "phone": "..." } }). The object key is the category; in the dashboard it renders as a category card.
Read: GET returns the same shape that was written (no flattening).
Rules / webhooks: read the stored shape — attributes.phone for flat, attributes.contact.phone for nested. Use identifier-safe category keys.

See Get entity and Update entity.

APIWebhooksEntities

Entity country activations API + webhook

Per-merchant country activation (operational flag)

Additive. Activate or deactivate supported countries per entity without changing entity profile data:

GET /entities/{id}/country-activations — lists AR, BR, CL, CO, MX, US; missing rows = deactivated (opt-in).
PATCH /entities/{id}/country-activations/{countryCode} — body { "status": "deactivated" | "activation_requested" | "activation_in_progress" | "activated" }; requires entities:edit. Free-form transitions. Idempotent when status unchanged (no webhook).
Webhook entity.country_activation_changed — emitted on every real status change; includes activeCountryCodes, full countries snapshot, and per-country timeline; subscribe via existing webhook config.

See List country activations, Update country activation, and Entity webhook events.

APIBulk imports

Bulk import: user events error policy parity

User event batch import — row error policy

Additive. User event CSV imports now match entity and transaction batch behavior:

POST /batch-import/import/user-events accepts optional multipart field batchErrorHandling: continue_collect_errors (default), rollback_all, or stop_keep_success.
202 responses include preflightFailures when invalid rows are skipped under continue policy.
POST /batch-import/validate-csv validates each row when the mapping target is user_event (rowErrors, validRowCount, invalidRowCount).

See Import user events and Validate CSV.

RulesAPI

Rules create: mandatory AI review + provenance

`POST /rules` — synchronous AI review on every create

New rules are always stored as in_progress with enabled: false; request status / enabled on create are ignored.
The response includes aiReview (verification summary) and may take several seconds.
Optional body creationProvenance records origin (user, agent, import_json, template, bundle, api) and optional agent chat ids.
AI review is audited but not debited from the AI token wallet.

See Create Rule.

WebhooksSecurityIAM

Security webhooks: invitation context fields

`security.member.invited` / `security.member.created` — richer `payload.context`

Additive. Invitation lifecycle webhooks now include correlation and access metadata in payload.context:

invitationId — correlate invited → created
granularRoleIds, granularRoleIdsSandbox
includeProduction, includeSandbox
teamId, teamIdSandbox
hasEnvironmentAccess — access flag for the org in the envelope
environment — "production" or "sandbox" for the envelope org
invitedByUserId, acceptedVia (on created)
syncPartialFailure, syncErrorMessage (on created when secondary setup did not fully complete)

Existing fields are unchanged. See Security webhook events.

APIBulk imports

Batch import: poll job status by jobId

Batch import job polling

Additive. New canonical endpoint for integrators to poll a single batch import job without scanning paginated history.

HTTP endpoints

GET /batch-import/jobs/{jobId} — direct lookup by job id across entity, transaction, and user-event imports. Returns status, counters (totalItems, succeeded, failed, skipped), timestamps, and optional jobFailure when the whole job aborted. Optional query include=failures returns the same JSON as the kind-specific failures endpoints (row-level failures[]).
GET /batch-import/unified-history — new optional query param jobId (exact match; 0 or 1 row). Unified history remains for listing recent jobs; use GET /batch-import/jobs/{jobId} for polling after upload.

Recommended integrator flow

Upload (202 + jobId) → poll GET /batch-import/jobs/{jobId} every 2–5s until terminal status → fetch failures if needed.See Get batch job status and Unified history.

MarketplaceAPIRules

Holder CBU/CVU intelligence: exists + accounts-count + metrics

Holder CBU/CVU intelligence (`ar_gueno_holder_intelligence_service`)

Additive. Account totals endpoint is accounts-count (replaces pre-release cbu-count). Returns snapshotDate, isNew, cbuCount, cvuCount, and totalAccounts.

HTTP endpoints

GET /api/integration-services/ar_gueno_holder_intelligence_service/health — service availability and corpus freshness (status, corpusFreshnessDate). No billing.
GET /api/integration-services/ar_gueno_holder_intelligence_service/cuits/:cuit/exists — corpus membership check. Returns found and snapshotDate (null when not found). Always HTTP 200 on success (including found: false). No billing.
GET /api/integration-services/ar_gueno_holder_intelligence_service/cuits/:cuit/accounts-count — CBU/CVU totals plus isNew and snapshotDate. Billable per request when priced.
GET /api/integration-services/ar_gueno_holder_intelligence_service/cuits/:cuit/metrics — densified incremental lookback (lookback 1–180 or window preset w_1d…w_180d). Optional query date (YYYY-MM-DD, inclusive window end). Returns stock aliases, deltas, %, variance, and acceleration. Billable per request when priced. Errors: 400 LOOKBACK_REQUIRED / INVALID_LOOKBACK / INVALID_WINDOW / INVALID_DATE, 404 CUIT_NOT_FOUND, 422 INCOMPLETE_WINDOW / NO_INCREMENTAL_STATE.

Rules engine

New condition fields under services.holder_intelligence.*: found, snapshot_date, cbu_quantity, cvu_quantity, total_accounts, and nested metrics.* with per-condition holderIntelligenceLookbackDays (1–180). On transaction rules the window ends on transactedAt by default. Metrics trigger a separate billable upstream fetch when referenced.See Provider codes and Marketplace Services (per-endpoint reference).

DocsMarketplaceAPI

Marketplace Services documentation section

Marketplace Services docs (en / es / pt)

New sidebar section Services with overview, per-service guides, and one page per HTTP endpoint for ar_gueno_holder_intelligence_service. Services overview.

KYCBiometricAPIEntities

KYC & biometric: entityTaxId / entityExternalId

Entity identifiers beyond `entityId`

Additive — backward compatible. Existing clients sending only entityId behave unchanged.

Create (POST)

POST /api/kyc/validations — body accepts entityId, entityExternalId, or entityTaxId (exactly one required).
POST /api/kyc/biometric/sessions — same identifier options.

Gu1 resolves entityExternalId / entityTaxId to the internal entity UUID. Returns 404 NOT_FOUND if no persisted entity matches.

Read (GET)

GET /api/kyc/validations?entityTaxId=... or ?entityExternalId=... (mutually exclusive with entityId).
GET /api/kyc/biometric/sessions?entityTaxId=... or ?entityExternalId=...
KYC: GET /api/kyc/entities/by-tax-id/:taxId/current|validations|status and .../by-external-id/:externalId/...
Biometric: GET /api/kyc/biometric/entities/by-tax-id/:taxId/current and .../by-external-id/:externalId/current

Sandbox entity preview (GET only)

GET /api/entities/by-tax-id/{taxId} and GET /api/entities?taxId=... may return sandboxMock: true synthetic data for catalog test document numbers when no real row exists (id: null). Does not enable POST without creating a real entity.

See Create KYC validation, Embedded biometric session, and Sandbox mock data.

KYCBiometricAPI

KYC & biometric create: blocking IDs on 409

Additive 409 responses for open sessions / validations

No breaking change for clients that only read error and message. New optional fields on existing 409 codes:

Embedded biometric — `POST /api/kyc/biometric/sessions`

While the latest session is pending or in_progress, create always returns 409 ACTIVE_SESSION_EXISTS (never 201 with the same pending session).
Body includes activeSessionId for cancel: POST .../sessions/{activeSessionId}/cancel.

KYC validation — `POST /api/kyc/validations`

While the entity has an open validation (pending, in_progress, in_review), create returns 409 VALIDATION_IN_PROGRESS.
Body now also includes activeValidationId for cancel: DELETE .../validations/{activeValidationId}/cancel.

See Create KYC validation and Embedded biometric session.

APITransactionsRules

GET transaction: optional rulesExecutionSummary on persisted

`includeRulesSummary` on single-transaction GET

GET /transactions/{id} and GET /transactions/external/{externalId} accept an optional query parameter:

includeRulesSummary=full — Adds persisted.rulesExecutionSummary from the latest risk_analysis_audits row for that transaction. Rules are not re-executed on read.

Default (param omitted): unchanged response — no rulesExecutionSummary on read. Use full only for detail views or debugging, not high-volume list polling.See Get transaction and Rules execution summary.

APIRulesTransactions

Rules execution summary: transaction party entity status

Optional fields in `rulesExecutionSummary`

When transaction rules use updateEntityStatus with origin or destination party entity status, the API may now include these optional fields (additive; existing clients unchanged):

rulesHit[].actions.originEntityStatus / destinationEntityStatus — configured on the matched rule.
actionsExecuted.originEntityStatus / destinationEntityStatus — final entity statuses applied in that run (alongside existing actionsExecuted.status for transaction status).

Audit rule snapshots now retain the full configured action list (including deferred status actions) for UI and integrators.See Rules Execution Summary.

WebhooksSecurityIAM

Security webhooks: unified member + environments

`security.member.*` events (unified naming)

All IAM events about people use the security.member.* prefix (no more security.user.*, security.team.*, or security.channel.*):

Profile / password: security.member.profile_updated, .password_reset, .password_generated
Teams: security.member.team_added, .team_removed, .team_role_changed
Channels (child org): security.member.channel_granted, .channel_revoked
Environment access (production / sandbox): security.member.environment_granted, .environment_revoked — use context.environment ("production" | "sandbox")

Team membership changes no longer emit misleading security.role.assigned / security.role.updated events.Breaking: if you subscribed to security.user.password_* or other legacy keys, migrate to the matching security.member.* keys.See Security webhook events.

KYCBiometricAPI

Biometric current session endpoint

`GET /api/kyc/biometric/entities/:entityId/current`

Aligned with KYC GET /api/kyc/entities/:entityId/current:

Returns the latest biometric session for the entity (by createdAt), any status (pending, in_progress, approved, rejected, …).
200 with null when the entity has no biometric sessions (no longer 404).
List endpoint currentSessionId still refers to the latest approved session only.

409 ACTIVE_SESSION_EXISTS on create now includes activeSessionId so integrators can cancel the blocking session without an extra lookup.See Current biometric session.

WebhooksSecurityIAM

Security & IAM webhook events

Security webhook events (`security.*`)

New outbound webhook category for Security / IAM monitoring (SIEM integrations). Subscribe in Webhooks → Configuration to events such as:

Auth: security.auth.login_succeeded, security.auth.logout, security.auth.login_failed
Members: security.member.invited, .created, .removed, .activated, .deactivated
Roles: security.role.created, .updated, .deleted, .assigned, .revoked
RBAC: security.rbac.granular_toggled
Password (admin): security.member.password_reset, security.member.password_generated (formerly security.user.password_*)
Settings: security.settings.updated (sandbox, audited org security settings)

Payload includes normalized actionAt, actor, affectedUser, description, changes (previous/current), and context (IP, user agent, scope).Not covered: Clerk self-service password change, MFA/SSO in Clerk, API-key auth.See Security webhook events.

Risk matricesEntitiesTransactionsAPI

Risk matrix watchFields + entity_updated runtime

Granular matrix triggers (`watchFields`)

Risk matrix event triggers entity_updated (entities and KYT transaction updated) support optional watchFields: an array of rule-engine field paths (e.g. email, phone, attributes.clientTypes, metadata.email). When omitted or empty, any change on that event runs the matrix (backward compatible). When set, the matrix runs only if at least one listed path changed.Configure in the Risk Matrix editor (Triggers tab) or via API in risk_matrices.triggers[].

Entity update — `entity_updated` wired

PATCH /entities/{id} (and by external ID / tax ID) now runs assigned matrices whose triggers include entity_updated, unless skipRulesExecution: true. The entity.updated webhook includes rulesExecutionSummary when rules ran or were skipped with a reason. See Update entity.Transaction PATCH with executeRules=true passes changed field paths to the same filter for transaction matrices.

EntitiesBulk importAPI

Bulk entity import — child enrichment policy

Bulk automatic entity import — child enrichments & monitoring scope

POST /batch-import/import/entities and JSON bulk automatic import accept two optional fields (automatic mode, depth > 0):

childEnrichmentPolicy: all_active (default), by_root_type, or basic_only.
- by_root_type: company rows run all active enrichments on shareholders except global_gueno_sanctions_enrichment; person rows create related entities with basic data only from the root provider snapshot.
monitoringApplyToRelationships: when false, monitoring applies to main entities only (no watchlist on children). Default true when depth > 0 if omitted.

The dashboard bulk entity import UI exposes the same controls. See Import entities (bulk).

EventsSDKAPI

SDK pre-login events and remote config

POST /events/user now accepts two optional fields: sessionId (SDK session id, sess_...) and sdkSignals (structured SDK signals — integrity and behavioral flags, kept separate from metadata). Both persist on the event. Omitting them keeps the previous behavior byte-for-byte.For organizations with the SDK enabled, an event carrying only a sessionId (no entityId/entityExternalId/taxId) is now accepted and stored as an anonymous pre-login event instead of returning an error; it is linked to the entity later, on the first event that carries both sessionId and an entity identifier. Without the SDK enabled, an entity identifier is still required (same response as before).

Events — new event types

Three SDK event types were added: SESSION_STARTED, SESSION_IDENTIFIED, SCREEN_VIEW. Existing clients are unaffected.

New endpoint — `GET /sdk/config`

Returns the SDK remote config (signal toggles + transport defaults) plus the organization’s sdkEnabled flag.See Create User Event.

EnrichmentEntitiesAPI

Enrichment errors and tax ID validation

Marketplace enrichment — structured errors

POST /integration-execution/marketplace/enrichment now returns richer per-integration error objects: optional category, retryable, and statusCode alongside code and message. Codes distinguish configuration issues (integration not enabled), timeouts, provider HTTP failures, and validation errors.

Automatic / bulk entity creation — tax ID strictness

taxId on automatic and bulk creation must be only the fiscal identifier. Values merged with spreadsheet columns (e.g. CNPJ plus business segment text) are rejected with INVALID_TAX_ID.

Transactions — optional `exchangeRate` fallback

POST /transactions and batch create accept optional exchangeRate on each transaction. Omitting it keeps the previous behavior (automatic conversion via the currency service).Used only when automatic conversion is unavailable. Semantics: base-currency units per 1 unit of currency; normalized base amount = amount × exchangeRate. Sets rateSource: client-provided.Non-convertible today (no automatic rate): WLD (Worldcoin), ETH (Ethereum). Send exchangeRate for a normalized base-currency amount and FX-dependent rules.See Create Transaction — Currency conversion.

EntitiesEnrichmentAPIDocs

Entities — refresh scope and preserve flags

`POST /entities/{entityId}/refresh` — unified scope and safe field sync

New optional body fields (all backward compatible when omitted):

refreshScope: basic_data | all_active | selected (+ providerCodes when selected).
preserveName: true keeps the current display name; omitted = legacy sync from normalized fullName.
preserveEntityData: only with refreshScope: "basic_data" — true gap-fills entityData, false replaces; omitted = do not touch profile.

basic_data always runs root-only (no shareholders), regardless of depth.See Refresh Entity. Existing Risk Matrix / integration payloads without these fields behave unchanged.

KYCAPIDocs

KYC — cross-entity duplicate warning

`GUENO_CROSS_ENTITY_DUPLICATED` warning

When Gu1 resolves provider duplicate session/face references to another entity in the same organization (metadata.kycCrossEntityDuplicates.matches):

Appends warning GUENO_CROSS_ENTITY_DUPLICATED to session validation warnings.
If the provider mapped approved, Gu1 sets status to in_review (metadata.guenoCrossEntityDuplicateEscalation).
Non-omittable: cannot be sent in omitWarnings (400) and blocks omit auto-approve.

Documented in KYC warning risk codes and omitWarnings.

KYCAPIWebhooksDocs

KYC — Gu1 Biometric

Gu1 Biometric (`POST /api/kyc/biometric` and `/api/kyc/biometric/sessions`)

Re-authentication after approved KYC: image upload check or hosted UI session (sessionUrl, iframeAllow, hostedSessionId, optional webhookUrl, org webhooks biometric.session_*, Gu1 status / rejectionCode). Marketplace product global_gueno_biometric_kyc. See Biometric verification, Biometric session, and Biometric webhook events.

KYCAPIWebhooksDocs

KYC — decision dual array/object shape

`decision` always includes array + object feature pairs

On persist (sync, webhook ingest, manual ingest), Gu1 normalizes decision so integrators can read either legacy singular keys or array keys interchangeably:

id_verification ↔ id_verifications[0]
liveness ↔ liveness_checks[0]
face_match ↔ face_matches[0]
aml_screening ↔ aml_screenings[0]
ip_analysis ↔ ip_analyses[0]

When both shapes were present, array[0] wins and the singular object is synchronized. Applies to GET validation responses and KYC webhooks (payload.decision).Mintlify examples updated with complete decision payloads (no vendor branding; media as kyc/... keys). See KYC webhook events.

EntitiesRisk MatrixAPIDocs

Risk matrix — rulesEngineConfig on analyze

Per-run rules engine config on `POST /entities/{entityId}/analyze`

New optional body object rulesEngineConfig (all fields default false):

partialCoverage: with multiple assigned matrices, data coverage is validated per matrix; matrices without data are skipped (matricesSkippedForCoverage / warnings on partial success).
omitCoverage: skip data coverage gates entirely (main entity + shareholders). Precedence over partialCoverage when both are true.

Default unchanged: union coverage blocks the whole run on any missing field (422 INCOMPLETE_DATA_COVERAGE).See Analyze Entity and Execute Risk Matrix.

KYCAPIDocs

KYC — extractedData.ejemplar (Argentine DNI)

`ejemplar` in extractedData

Argentine DNI verifications can include extractedData.ejemplar (A–D) on KYC validations and ID Verification audit records (GET, sync, webhooks).With doubleCheckRenaper: true, comparisonResults.ejemplar compares OCR vs RENAPER; mismatch adds RENAPER_EJEMPLAR_NOT_MATCH to warnings.See extractedData fields and RENAPER double-check.

KYCAPIDocs

KYC — RENAPER flow and manual review

RENAPER double-check on KYC validations

With doubleCheckRenaper: true, metadata.responseDoubleChecks.renaper includes comparisonResults, renaperBiometric (when applicable), and RENAPER codes in warnings (e.g. RENAPER_TRAMITE_ID_NOT_MATCH, RENAPER_EXPIRY_NOT_MATCH) without replacing OCR KYC verification warnings.Enforcement (auto-reject): only when OCR KYC verification returns status approved. On in_review and rejected the check is informational and stores registry data. POST /api/kyc/validations/{id}/approve from in_review does not re-run RENAPER.See Create KYC validation and Approve validation.

EntitiesEnrichmentAPIDocs

Marketplace — checks removed, enrichments only

Marketplace `*_check` product removed

Removed: all *_check provider codes, POST /integration-execution/marketplace/check, rules triggers/actions check_completed / execute_check, and RBAC permissions checks:read / checks:execute.
Use instead: matching *_enrichment codes with Execute enrichment.
Backward compat: legacy create/import payloads with checks, executeAllActiveChecks, or *_check inside autoExecuteIntegrations.enrichments are silently ignored at parse time.

See Provider codes, Create entity, and Create automatically.

Bulk importsAPIDocs

Bulk imports — failure codes + JSON failures

Stable batch failure codes and JSON endpoints

Row failures now include stable code + message (catalog: Failure codes). CSV adds a code column (external_id,code,error / row_key,code,error / entity …,code,error_message).
New JSON endpoints: GET /batch-import/transaction-jobs/{jobId}/failures, GET /batch-import/user-event-jobs/{jobId}/failures, GET /batch-import/entity-jobs/{jobId}/failures — include failures[], optional jobFailure for whole-job errors, entity skips[], truncated / failuresTotal (max 500 stored).
CSV download: same routes with .csv suffix (failures.csv).
Legacy rows with only free-text error are normalized on read when possible.

EntitiesAPIDocs

Entities — PATCH riskMatrixIds

Assign risk matrices on entity update

PATCH /entities/{id} (and PATCH /entities/by-external-id/{externalId}, PATCH /entities/by-tax-id/{taxId}): document riskMatrixIds (string[]) and riskMatrixId (string | string[] | null) — same normalization as create. Assigns matrices on the entity; does not run the rules engine (use Analyze entity or lifecycle triggers).
Mintlify updated in /en/, /es/, /pt/ on Update entity and Update by external ID.

TransactionsRulesAPIDocs

Transactions — configRulesExecution.notifications

`configRulesExecution` on create transaction

POST /transactions: optional body object configRulesExecution with notifications (boolean). When false, gu1 skips in-app notifications from rules evaluation (risk matrix / status). createAlert actions and investigations are unchanged.
Default: omitting the object keeps prior behavior for most orgs (notifications effectively true). Paytime prod (3bc1f621-27d4-423e-9d64-86680bec2388) defaults to notifications: false when omitted.
Legacy KYT POST /legacy/kyt/verifyTransaction: same field on the Gu2 body; Paytime prod default notifications: false when omitted (normalized before create).
Applies to sync and async rules (asyncRules).

See Create transaction. Parity in /es/ and /pt/.

TransactionsAPIDocs

Transactions — canonical entity denormalization on link

`POST /transactions` and batch create — linked counterparty fields

When origin or destination is linked to a person/company (originEntityId / auto-link by external or tax id), gu1 always overwrites denormalized columns from the entity row before insert:

originTaxId / destinationTaxId ← entities.tax_id
originExternalId / destinationExternalId ← entities.external_id

Client-sent values for those fields are not kept if they differ from the linked entity. This aligns transaction monitoring rules with user events stored under the same entity identifiers.Documented in Create transaction and Create batch. Parity in /es/ and /pt/.

EventsAPIDocs

User events — isNewDevice client priority

`POST /events/user` — `isNewDevice` honors integrator value

If you send isNewDevice: true or false, gu1 persists exactly that value (no server override).
If you omit the field, gu1 infers it when deviceId + deviceDetails are present (device registry; true when the device is new or firstSeenAt is within the last 5 minutes); otherwise false.

Documented in Create user event and Events overview. Parity in /es/ and /pt/.

EntitiesBulk importAPI

Entity import — attributes / entityData dot notation

Platform CSV: `attributes.` and `entityData.`

Dotted headers (same approach as native transaction CSV): attributes.segment_tag, entityData.income, entityData.tradeName.
entityData.<field> without person/company uses the row type bucket.
Unprefixed columns (segment_tag) still map to attributes (backward compatible).
See Import entities (CSV).

Bulk importAPIDocs

Bulk imports — limits and manual vs automatic

Import limits documented (en / es / pt)

Bulk imports overview: matrix of max files per request, max rows by plan, and manual vs automatic entity import.
Per-endpoint pages now include limits: Import entities (CSV), Import transactions, Import user events.
CSV entity import uses plan limits (4k–100k). Runtime caps: GET /individual-organization/batch-upload-enabled.

Parity in /es/ and /pt/ docs.

EntitiesBulk importAPI

Entity import — countries by mode

Bulk entity import countries (manual vs automatic)

Manual (manual): any valid platform ISO2 (batch or per-row country / country_code).
Automatic (automatic): AR, BR, and CL (basic data by tax ID, including Chile ruts.info / BaseAPI enrichments).
Applies to POST /batch-import/import/entities (platform CSV and custom CSV with mappingId).

See Import entities (CSV).

EntitiesBulk importAPI

Entity import — manual multipart alignments

`POST /batch-import/import/entities` — manual mode enrichments

Manual multipart now matches the dashboard Manual hub mode: optional autoExecuteIntegrations, monitoring, and risk matrices — without the country basic-data pipeline (Nosis/CPF).
CSV-only upload (no autoExecuteIntegrations) still creates minimal entities with no enrichments.
Per-row CSV enrichment columns apply in manual mode; depth / shareholders remain automatic-only.

See Import entities (CSV).

EntitiesBulk importAPI

Entity import — API default manual

`POST /batch-import/import/entities` — manual default

Omitting entityImportMode → manual (minimal entity; enrichments only when explicitly requested).
Automatic with entityImportMode=automatic (+ optional autoExecuteIntegrations, depth, etc.).
Manual mode requires suggested_name on every row (400 if missing).
Template bulk-entities-template.csv: documented columns; demo row without active enrichments.
202 response includes effective importMode.

See Import entities (CSV).

EntitiesBulk importAPI

Entity import — platform CSV without mappingId

`POST /batch-import/import/entities` — platform format

mappingId optional for platform CSV headers. Import default: manual (see next changelog entry on this date).

See Import entities (CSV).

TransactionsRulesAPI

Async transaction rules evaluation

`asyncRules` on create transaction

POST /transactions: optional query or body flag asyncRules (default false). When true and executeRules is not false, the transaction is created in the same request but rules run in the background via a job queue. The HTTP response returns immediately with empty rulesHit / rulesNoHit, plus asyncRules: true and rulesEvaluationStatus: "queued".
Default unchanged: omitting asyncRules keeps synchronous rules execution and a full rulesExecutionSummary — existing clients behave exactly as before.
Legacy KYT POST /legacy/kyt/verifyTransaction: same flag via query or Gu2 body field. Paytime prod (3bc1f621-27d4-423e-9d64-86680bec2388) defaults to async when the flag is omitted; use asyncRules=false to force synchronous rules for a single request.
Not on batch endpoints. If Redis/queue is unavailable, API may return 503 ASYNC_RULES_QUEUE_UNAVAILABLE (transaction may already exist — check response body before retry).

See Create transaction.

KYCAPI

Face Match & ID Verification — RENAPER double-check

RENAPER double-check on standalone KYC endpoints

POST /api/kyc/face-match: optional doubleCheckRenaper (body or ?doubleCheckRenaper=true). After Gu1 face match approves, runs RENAPER biometric (validate-dni with selfie) and data (DNI + trámite). Requires documentNumber, gender, and personalNumber (or entity fallback for DNI/gender). Response adds responseDoubleChecks.renaper (including nested renaperBiometric when biometric check runs).
POST /api/kyc/id-verification: same flag; after OCR approval runs RENAPER data check only (fields from extractedData). Failed checks set status to declined and add RENAPER codes to warnings.
Org RENAPER credentials required (same as session KYC). Use HTTP timeout ≥ 60s for face-match with double-check.

See Face Match and ID Verification.

TransactionsRulesAPI

Transaction status-change rule trigger

KYT — separate status-change vs field-update triggers

PATCH …/changeStatus now runs rules/matrices with trigger status_changed (trigger_transaction_status_changed), not updated.
PATCH /transactions/{id} (metadata, deviceDetails, channel, reason) with executeRules=true still uses updated (trigger_transaction_updated).
Migration: reconfigure rules that must run on status transitions to the new trigger (Rule Builder: On transaction status change; matrices: transaction_status_changed). Rules with only updated / Transaction updated no longer run on changeStatus.

See Change status and Update transaction.

TransactionsAPI

PATCH transaction — metadata, deviceDetails, channel, reason

Partial transaction update

PATCH /transactions/{id} and PATCH /transactions/external/{externalId}: update metadata (shallow merge — omitted keys are preserved), deviceDetails (shallow merge into device_details), channel (nullable), and/or reason (enum). Requires transactions:edit.
Query executeRules=true optionally re-runs KYT rules with trigger updated (trigger_transaction_updated) — not status-change rules.
Emits audit transaction_updated and webhook transaction.updated with a changes map (includes deviceDetails when patched).

See Update transaction.

EventsAPI

Has events by entity — query identifiers

User events — has-events by external ID or tax ID

GET /events/user/entity/has-events (new): boolean check without the internal entity UUID. Query params: entity_id, entity_external_id, or tax_id (at least one required). Lookup priority: entity_id → entity_external_id → tax_id; tax IDs are matched with normalization (non-alphanumeric stripped).
Response still includes resolved entityId so you can call List by Entity when hasEvents is true.
GET /events/user/entity/{entityId}/has-events remains supported (unchanged contract).

See Has events by entity.

KYCAPI

KYC IP analysis warning codes

Session KYC — Device & IP analysis warnings

GET /api/kyc/validations/:id (and sync/webhook paths): the top-level warnings array now merges risk codes from decision.ip_analyses[].warnings[] (and legacy decision.ip_analysis.warnings), alongside ID verification, liveness, face match, and AML.
Eight provider codes are supported (e.g. PRIVATE_NETWORK_DETECTED, DUPLICATED_DEVICE_FINGERPRINT, IP_ADDRESS_IN_BLOCKLIST). See KYC Warning Risk Codes — Device & IP Analysis.
The same codes are valid in omitWarnings on POST /api/kyc/validations when auto-approving in_review sessions.

Integrator note: Existing validations keep their stored warnings until the next sync; re-fetch or sync to backfill IP analysis codes on older rows.

KYCAPI

ID Verification extractedData expansion

ID Verification — richer `extractedData`

POST /api/kyc/id-verification and audit list/get now persist and return a broader extractedData object: identity fields (personalNumber, taxNumber, placeOfBirth, …), providerStatus, warningMeta (e.g. duplicate session IDs), quality scores, extraFields, mrz, parsedAddress, barcodes when returned by the Gu1 ID Verification service.
warnings remains a string array of risk codes for i18n; use warningMeta inside extractedData for structured duplicate-session metadata.
External document image URLs and base64 are not returned; images you uploaded are available via ID Verification images.
debugProviderResponse may appear only in non-production Gu1 API environments (sanitized verification payload, no images).

See ID Verification.

EntitiesTransactionsRulesAPI

Entity operationalHours + KYT operational hours rules

operational hours per entity (global)

Entities: Optional root field operationalHours (timezone enum + weekly slots). Stored in entities.operational_hours. Documented on Create entity and related entity endpoints.
Transactions: transaction_time_zone enum extended (Brazil zones). Optional timeZone is independent of entity operationalHours. transactedAt: stored as UTC; ISO with Z unchanged for existing clients; optional local datetime + timeZone converts to UTC when both are sent.
Rules: New operators outside_entity_operational_hours and inside_entity_operational_hours on transactedAt with value origin or destination. Requires operationalHours on the linked entity.

See Create transaction and transactional rules knowledge base.

TransactionsAPIDatabase

Optional timeZone on transactions

`timeZone` on transactions

Database: New nullable column time_zone on transactions with enum type transaction_time_zone (IANA values such as America/Argentina/Buenos_Aires, UTC, etc.). Existing rows remain null.
API: Optional timeZone on POST /transactions and batch create; returned on GET /transactions/{id} and GET /transactions/external/{externalId} as string | null.

See Transaction Time Zone Enum and Create transaction.

TransactionsAPILegacy

validateExistingEntity on transactions

`validateExistingEntity` (transaction create)

POST /transactions: optional validateExistingEntity (default false). When true, every origin/destination identifier you send must resolve to an existing person/company; otherwise 400 INVALID_ENTITY_REFERENCES and no row is created.
Batch endpoints: default remains true. Use validateExistingEntity: false for permissive bulk import.
Legacy KYT POST /legacy/kyt/verifyTransaction: same field in the Gu2 body.

See Create transaction and Batch create.

EntitiesAPIEnrichment

Entity creation auto-execute

`excludeEnrichments` on entity creation

autoExecuteIntegrations and autoExecuteIntegrationsShareholders (manual POST /entities, POST /entities/automatic, bulk import, materialize) now accept excludeEnrichments: an array of provider codes removed from the final enrichment set after merge (including when executeAllActiveEnrichments is true).executeAllActiveChecks and checks are no longer part of the public contract for these objects. Legacy payloads that still send them are ignored at parse time.See Create entity (automatic) and Create entity.

KYCHosted PageDocumentation

v1.3.0 - Hosted Onboarding Page Documentation

New: Hosted Onboarding Page Documentation

Complete documentation for the Hosted Onboarding Page - the quickest way to implement KYC verification without code.

What’s New

Hosted Page Documentation:

✅ Complete customization parameters guide (branding, colors, layout)
✅ Validation rules configuration (age verification, capture methods, duplicate detection)
✅ Document validation rules (QR/barcode, MRZ, expiration dates, liveness)
✅ Step-by-step integration guide with code examples
✅ Visual flow diagram showing the complete process
✅ Security best practices for session management
✅ Mobile-responsive design confirmation

Key Features:

📱 Mobile-responsive design for all devices
🎨 Full customization of colors, branding, and layout
🔒 Comprehensive security guidelines
📊 Visual sequence diagrams for clarity
🌐 Support channel information for configuration changes

Languages

All documentation available in:

🇺🇸 English
🇪🇸 Español
🇧🇷 Português

Impact

Faster implementation for no-code solutions
Clear guidance on customization options
Enhanced security awareness
Better understanding of the hosted page workflow

View Hosted Page Documentation

KYCDocumentationMulti-language

v1.2.0 - KYC Documentation Enhancement

Major enhancement to KYC documentation based on 14 questions from client feedback.

What’s New

Complete Flow Documentation:

✅ Added comprehensive comparison table: Automatic vs Manual creation
✅ Complete Risk Matrix configuration guide with dashboard instructions
✅ Clarified shareholders feature (KYB only, not KYC)
✅ Provider codes reference with usage examples
✅ Detailed credit management section with costs and workflows

Overview Page:

✅ Webhooks vs manual polling explanation
✅ Full KYC vs Individual Verifications comparison table
✅ Comprehensive face matching security warning for banks/fintech
✅ Enhanced API endpoints table with use cases

Create Validation Page:

✅ Complete sequence diagram showing full flow
✅ Sandbox vs Production clarification
✅ Duplicate entity handling with code examples
✅ Expanded integrationCode documentation

Entities API:

✅ Marked optional fields with examples (attributes, entityData)
✅ Minimal vs full entity creation examples

Languages

All improvements available in:

🇺🇸 English
🇪🇸 Español
🇧🇷 Português

Impact

14 client questions answered inline
12 documentation files updated
0 broken links
Improved developer onboarding experience

View KYC Documentation

Infrastructurei18n

v1.1.0 - Multi-language Support

Enhanced Multi-language Documentation

Improved documentation structure with complete Spanish and Portuguese translations.

Changes

Complete translation coverage for KYC, KYB, and Transaction Monitoring
Consistent terminology across all languages
Language-specific examples (CPF for Brazil, DNI for Spain, etc.)

Available Languages

English (EN) - Primary
Spanish (ES) - Complete
Portuguese (PT) - Complete

Launch

v1.0.0 - Initial Release

gu1 Documentation Launch

Initial release of comprehensive API documentation.

Core Features

Complete API reference for all endpoints
Use case guides (KYC, KYB, Transaction Monitoring)
Webhook integration guides
Interactive tutorials
Multi-language support

Components

Person entities API
Company entities API
KYC validation workflows
Transaction monitoring
Rules engine
Risk matrices
Alerts and investigations

Get Started

​Per-code KYC warning policy

​Configurable validation language

​Secure onboarding reactivation

​Share matrices, lists, and webhooks with channels

​Manual transaction risk reports

​CUIT demographics on accounts-count

​Main CNAE in Brazilian company profiles

​GET normalized enrichment and current enrichment data

​statusIds on the CPF in-list checks

​Integrator-facing error strings

​Account routes by external ID and tax ID

​Spain KYB tax IDs (autónomos)

​Entity accounts

​Rate limit wait in the 429 body

​Automatic vs manual entity rows

​Batch import concurrency and entity row cap

​Per-file retention in export history

​Closing related imports

​Devices for an entity and its direct relationships

​jobFailure.code: ARTIFACT_UPLOAD_FAILED and QUEUE_ERROR

​validate-csv: row-level warnings for transaction mappings

​New entity status: awaiting_information

​Marketplace service: Central de Prevención de Fraude (CPF)

​Entity report: explicit current risk and AML screening

​Transactions: MCC length relaxed

​AML Crypto: client-flow parity

​POST /automations/from-template always creates disabled

​Automation template: entity monitoring (scheduled)

​Automation templates: preconfig params + alert → email

​Editable presets + preview + CSV/PDF

​Report generate → async S3 + Descargables

​Report presets API

​Report templates API

​Automations on investigation status change

​New entity status: not_started

​Total CBU+CVU delta and percent change on metrics

​autoExecuteIntegrations.enrichments is filtered by country and entity type

​Create notes on an entity dossier

​New row failure code: SCIENTIFIC_NOTATION_ID

​Row error policy and S3 artifacts for transaction batch

​Latest rules evaluation date filter

​Additional fields in legacy flat entity webhooks

​Skipped rows report for transaction batches

​Declared relationships on duplicate tax_id (bulk)

​Link to existing entities on create and bulk import

​security.member.environment_changed

​Entity link: soft-link always, strict default unchanged for batch

​Error code: CREATION_CONTRACT_QUOTA_EXCEEDED

​Tax ID uniqueness (org-wide)

​New rule action: addFieldToCustomList

​Creation blocklist (risk analysis settings)

​Dedicated attributes update endpoint

​Custom attributes stored verbatim (API)

​Per-merchant country activation (operational flag)

​User event batch import — row error policy

​POST /rules — synchronous AI review on every create

​security.member.invited / security.member.created — richer payload.context

​Batch import job polling

​HTTP endpoints

​Recommended integrator flow

​Holder CBU/CVU intelligence (ar_gueno_holder_intelligence_service)

​HTTP endpoints

​Rules engine

​Marketplace Services docs (en / es / pt)

​Entity identifiers beyond entityId

​Create (POST)

​Read (GET)

​Sandbox entity preview (GET only)

​Additive 409 responses for open sessions / validations

​Embedded biometric — POST /api/kyc/biometric/sessions

​KYC validation — POST /api/kyc/validations

​includeRulesSummary on single-transaction GET

​Optional fields in rulesExecutionSummary

​security.member.* events (unified naming)

​GET /api/kyc/biometric/entities/:entityId/current

​Security webhook events (security.*)

​Granular matrix triggers (watchFields)

​Entity update — entity_updated wired

​Bulk automatic entity import — child enrichments & monitoring scope

​Events — SDK session fields and pre-login

Per-code KYC warning policy

Configurable validation language

Secure onboarding reactivation

Share matrices, lists, and webhooks with channels

Manual transaction risk reports

CUIT demographics on accounts-count

Main CNAE in Brazilian company profiles

GET normalized enrichment and current enrichment data

`statusIds` on the CPF in-list checks

Integrator-facing `error` strings

Account routes by external ID and tax ID

Spain KYB tax IDs (autónomos)

Entity accounts

Rate limit wait in the 429 body

Automatic vs manual entity rows

Batch import concurrency and entity row cap

Per-file retention in export history

Closing related imports

Devices for an entity and its direct relationships

`jobFailure.code`: `ARTIFACT_UPLOAD_FAILED` and `QUEUE_ERROR`

`validate-csv`: row-level warnings for transaction mappings

New entity status: `awaiting_information`

Marketplace service: Central de Prevención de Fraude (CPF)

Entity report: explicit current risk and AML screening

Transactions: MCC length relaxed

AML Crypto: client-flow parity

`POST /automations/from-template` always creates disabled

Automation template: entity monitoring (scheduled)

Automation templates: preconfig params + alert → email

Editable presets + preview + CSV/PDF

Report generate → async S3 + Descargables

Report presets API

Report templates API

Automations on investigation status change

New entity status: `not_started`

Total CBU+CVU delta and percent change on metrics

`autoExecuteIntegrations.enrichments` is filtered by country and entity type

Create notes on an entity dossier

New row failure code: `SCIENTIFIC_NOTATION_ID`

Row error policy and S3 artifacts for transaction batch

Latest rules evaluation date filter

Additional fields in legacy flat entity webhooks

Skipped rows report for transaction batches

Declared relationships on duplicate `tax_id` (bulk)

Link to existing entities on create and bulk import

`security.member.environment_changed`

Entity link: soft-link always, strict default unchanged for batch

Error code: `CREATION_CONTRACT_QUOTA_EXCEEDED`

Tax ID uniqueness (org-wide)

New rule action: `addFieldToCustomList`

Creation blocklist (risk analysis settings)

Dedicated attributes update endpoint

Custom attributes stored verbatim (API)

Per-merchant country activation (operational flag)

User event batch import — row error policy

`POST /rules` — synchronous AI review on every create

`security.member.invited` / `security.member.created` — richer `payload.context`

Batch import job polling

HTTP endpoints

Recommended integrator flow

Holder CBU/CVU intelligence (`ar_gueno_holder_intelligence_service`)

HTTP endpoints

Rules engine

Marketplace Services docs (en / es / pt)

Entity identifiers beyond `entityId`

Create (POST)

Read (GET)

Sandbox entity preview (GET only)

Additive 409 responses for open sessions / validations

Embedded biometric — `POST /api/kyc/biometric/sessions`

KYC validation — `POST /api/kyc/validations`

`includeRulesSummary` on single-transaction GET

Optional fields in `rulesExecutionSummary`

`security.member.*` events (unified naming)

`GET /api/kyc/biometric/entities/:entityId/current`

Security webhook events (`security.*`)

Granular matrix triggers (`watchFields`)

Entity update — `entity_updated` wired

Bulk automatic entity import — child enrichments & monitoring scope

Events — SDK session fields and pre-login