Skip to main content




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
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
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).
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.
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

Events β€” SDK session fields and pre-login

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)

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

KYC Pages Refinement Based on Client Feedback

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