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.Additional fields in legacy flat entity webhooks
Legacy flat entity webhook payloads now include the additive fieldsriskScore and
documentNumber. Existing status values and mappings remain unchanged.See Entity webhook events.Skipped rows report for transaction batches
New endpointGET /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; withskipDuplicates=falseduplicates are resolved by the database and only counted, so the endpoint returnsSKIPS_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.
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).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 /entitiesandPOST /entities/automatic: optionalrelationships[]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_FOUNDand the entity is not created.
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
security.member.environment_granted / .environment_revoked remain for single-environment grant/revoke flows.See Security webhook events.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 β
validateExistingEntitystill defaults totrue. Unresolved refs β 400INVALID_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 ifvalidateExistingEntitywould otherwise be true.validateExistingEntity=false: soft-link (and still attaches when found β previously soft mode skipped linking on batch).
POST /transactions keeps validateExistingEntity default false.See Create batch.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 historicalfailures.csv.
Tax ID uniqueness (org-wide)
An activetaxId (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 β
409with codeDUPLICATE_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.
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).primaryValue entries are ignored. Available on universal rule POST/PUT and in the Rule Builder.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.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 keptmode: replaceβ bodyattributesbecomes the full map ({}clears all)- Nested category buckets supported on write (same as entity update)
- Triggers
entity.updatedwebhook and risk matrices withentity_updatedtrigger when configured
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:
GETreturns the same shape that was written (no flattening). - Rules / webhooks: read the stored shape β
attributes.phonefor flat,attributes.contact.phonefor nested. Use identifier-safe category keys.
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" }; requiresentities:edit. Free-form transitions. Idempotent when status unchanged (no webhook).- Webhook
entity.country_activation_changedβ emitted on every real status change; includesactiveCountryCodes, fullcountriessnapshot, and per-countrytimeline; subscribe via existing webhook config.
User event batch import β row error policy
Additive. User event CSV imports now match entity and transaction batch behavior:POST /batch-import/import/user-eventsaccepts optional multipart fieldbatchErrorHandling:continue_collect_errors(default),rollback_all, orstop_keep_success.202responses includepreflightFailureswhen invalid rows are skipped under continue policy.POST /batch-import/validate-csvvalidates each row when the mapping target isuser_event(rowErrors,validRowCount,invalidRowCount).
POST /rules β synchronous AI review on every create
- New rules are always stored as
in_progresswithenabled: false; requeststatus/enabledon create are ignored. - The response includes
aiReview(verification summary) and may take several seconds. - Optional body
creationProvenancerecords 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.
security.member.invited / security.member.created β richer payload.context
Additive. Invitation lifecycle webhooks now include correlation and access metadata in payload.context:invitationIdβ correlateinvitedβcreatedgranularRoleIds,granularRoleIdsSandboxincludeProduction,includeSandboxteamId,teamIdSandboxhasEnvironmentAccessβ access flag for the org in the envelopeenvironmentβ"production"or"sandbox"for the envelope orginvitedByUserId,acceptedVia(oncreated)syncPartialFailure,syncErrorMessage(oncreatedwhen secondary setup did not fully complete)
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. Returnsstatus, counters (totalItems,succeeded,failed,skipped), timestamps, and optionaljobFailurewhen the whole job aborted. Optional queryinclude=failuresreturns the same JSON as the kind-specific failures endpoints (row-levelfailures[]).GET /batch-import/unified-historyβ new optional query paramjobId(exact match; 0 or 1 row). Unified history remains for listing recent jobs; useGET /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.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. ReturnsfoundandsnapshotDate(nullwhen not found). Always HTTP200on success (includingfound: false). No billing.GET /api/integration-services/ar_gueno_holder_intelligence_service/cuits/:cuit/accounts-countβ CBU/CVU totals plusisNewandsnapshotDate. Billable per request when priced.GET /api/integration-services/ar_gueno_holder_intelligence_service/cuits/:cuit/metricsβ densified incremental lookback (lookback1β180 orwindowpresetw_1dβ¦w_180d). Optional querydate(YYYY-MM-DD, inclusive window end). Returns stock aliases, deltas,%, variance, and acceleration. Billable per request when priced. Errors:400LOOKBACK_REQUIRED/INVALID_LOOKBACK/INVALID_WINDOW/INVALID_DATE,404CUIT_NOT_FOUND,422INCOMPLETE_WINDOW/NO_INCREMENTAL_STATE.
Rules engine
New condition fields underservices.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).Marketplace Services docs (en / es / pt)
New sidebar section Services with overview, per-service guides, and one page per HTTP endpoint forar_gueno_holder_intelligence_service. Services overview.Entity identifiers beyond entityId
Additive β backward compatible. Existing clients sending only entityId behave unchanged.Create (POST)
POST /api/kyc/validationsβ body acceptsentityId,entityExternalId, orentityTaxId(exactly one required).POST /api/kyc/biometric/sessionsβ same identifier options.
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 withentityId).GET /api/kyc/biometric/sessions?entityTaxId=...or?entityExternalId=...- KYC:
GET /api/kyc/entities/by-tax-id/:taxId/current|validations|statusand.../by-external-id/:externalId/... - Biometric:
GET /api/kyc/biometric/entities/by-tax-id/:taxId/currentand.../by-external-id/:externalId/current
Sandbox entity preview (GET only)
GET /api/entities/by-tax-id/{taxId}andGET /api/entities?taxId=...may returnsandboxMock: truesynthetic data for catalog test document numbers when no real row exists (id: null). Does not enable POST without creating a real entity.
Additive 409 responses for open sessions / validations
No breaking change for clients that only readerror and message. New optional fields on existing 409 codes:Embedded biometric β POST /api/kyc/biometric/sessions
- While the latest session is
pendingorin_progress, create always returns409 ACTIVE_SESSION_EXISTS(never201with the same pending session). - Body includes
activeSessionIdfor cancel:POST .../sessions/{activeSessionId}/cancel.
KYC validation β POST /api/kyc/validations
- While the entity has an open validation (
pending,in_progress,in_review), create returns409 VALIDATION_IN_PROGRESS. - Body now also includes
activeValidationIdfor cancel:DELETE .../validations/{activeValidationId}/cancel.
includeRulesSummary on single-transaction GET
GET /transactions/{id} and GET /transactions/external/{externalId} accept an optional query parameter:includeRulesSummary=fullβ Addspersisted.rulesExecutionSummaryfrom the latestrisk_analysis_auditsrow for that transaction. Rules are not re-executed on read.
rulesExecutionSummary on read. Use full only for detail views or debugging, not high-volume list polling.See Get transaction and Rules execution summary.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 existingactionsExecuted.statusfor transaction status).
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β usecontext.environment("production"|"sandbox")
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.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, β¦). 200withnullwhen the entity has no biometric sessions (no longer404).- List endpoint
currentSessionIdstill refers to the latestapprovedsession 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.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(formerlysecurity.user.password_*) - Settings:
security.settings.updated(sandbox, audited org security settings)
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.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.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, orbasic_only.by_root_type: company rows run all active enrichments on shareholders exceptglobal_gueno_sanctions_enrichment; person rows create related entities with basic data only from the root provider snapshot.
monitoringApplyToRelationships: whenfalse,monitoringapplies to main entities only (no watchlist on children). Defaulttruewhendepth> 0 if omitted.
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.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.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(+providerCodeswhenselected).preserveName:truekeeps the current display name; omitted = legacy sync from normalizedfullName.preserveEntityData: only withrefreshScope: "basic_data"βtruegap-fillsentityData,falsereplaces; 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.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_DUPLICATEDto session validationwarnings. - If the provider mapped
approved, Gu1 sets status toin_review(metadata.guenoCrossEntityDuplicateEscalation). - Non-omittable: cannot be sent in
omitWarnings(400) and blocks omit auto-approve.
omitWarnings.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.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]
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.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/warningson partial success).omitCoverage: skip data coverage gates entirely (main entity + shareholders). Precedence overpartialCoveragewhen both are true.
422 INCOMPLETE_DATA_COVERAGE).See Analyze Entity and Execute Risk Matrix.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.RENAPER double-check on KYC validations
WithdoubleCheckRenaper: 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.Marketplace *_check product removed
- Removed: all
*_checkprovider codes,POST /integration-execution/marketplace/check, rules triggers/actionscheck_completed/execute_check, and RBAC permissionschecks:read/checks:execute. - Use instead: matching
*_enrichmentcodes with Execute enrichment. - Backward compat: legacy create/import payloads with
checks,executeAllActiveChecks, or*_checkinsideautoExecuteIntegrations.enrichmentsare silently ignored at parse time.
Stable batch failure codes and JSON endpoints
- Row failures now include stable
code+message(catalog: Failure codes). CSV adds acodecolumn (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β includefailures[], optionaljobFailurefor whole-job errors, entityskips[],truncated/failuresTotal(max 500 stored). - CSV download: same routes with
.csvsuffix (failures.csv). - Legacy rows with only free-text
errorare normalized on read when possible.
Assign risk matrices on entity update
PATCH /entities/{id}(andPATCH /entities/by-external-id/{externalId},PATCH /entities/by-tax-id/{taxId}): documentriskMatrixIds(string[]) andriskMatrixId(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.
configRulesExecution on create transaction
POST /transactions: optional body objectconfigRulesExecutionwithnotifications(boolean). Whenfalse, gu1 skips in-app notifications from rules evaluation (risk matrix / status).createAlertactions and investigations are unchanged.- Default: omitting the object keeps prior behavior for most orgs (
notificationseffectivelytrue). Paytime prod (3bc1f621-27d4-423e-9d64-86680bec2388) defaults tonotifications: falsewhen omitted. - Legacy KYT
POST /legacy/kyt/verifyTransaction: same field on the Gu2 body; Paytime prod defaultnotifications: falsewhen omitted (normalized before create). - Applies to sync and async rules (
asyncRules).
/es/ and /pt/.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_idoriginExternalId/destinationExternalIdβentities.external_id
/es/ and /pt/.POST /events/user β isNewDevice honors integrator value
- If you send
isNewDevice: trueorfalse, gu1 persists exactly that value (no server override). - If you omit the field, gu1 infers it when
deviceId+deviceDetailsare present (device registry;truewhen the device is new orfirstSeenAtis within the last 5 minutes); otherwisefalse.
/es/ and /pt/.Platform CSV: attributes.* and entityData.*
- Dotted headers (same approach as native transaction CSV):
attributes.segment_tag,entityData.income,entityData.tradeName. entityData.<field>withoutperson/companyuses the rowtypebucket.- Unprefixed columns (
segment_tag) still map toattributes(backward compatible). - See Import entities (CSV).
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.
/es/ and /pt/ docs.Bulk entity import countries (manual vs automatic)
- Manual (
manual): any valid platform ISO2 (batch or per-rowcountry/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 withmappingId).
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.
POST /batch-import/import/entities β manual default
- Omitting
entityImportModeβmanual(minimal entity; enrichments only when explicitly requested). - Automatic with
entityImportMode=automatic(+ optionalautoExecuteIntegrations,depth, etc.). - Manual mode requires
suggested_nameon every row (400if missing). - Template
bulk-entities-template.csv: documented columns; demo row without active enrichments. 202response includes effectiveimportMode.
POST /batch-import/import/entities β platform format
mappingIdoptional for platform CSV headers. Import default:manual(see next changelog entry on this date).
asyncRules on create transaction
POST /transactions: optional query or body flagasyncRules(defaultfalse). WhentrueandexecuteRulesis notfalse, the transaction is created in the same request but rules run in the background via a job queue. The HTTP response returns immediately with emptyrulesHit/rulesNoHit, plusasyncRules: trueandrulesEvaluationStatus: "queued".- Default unchanged: omitting
asyncRuleskeeps synchronous rules execution and a fullrulesExecutionSummaryβ 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; useasyncRules=falseto 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).
RENAPER double-check on standalone KYC endpoints
POST /api/kyc/face-match: optionaldoubleCheckRenaper(body or?doubleCheckRenaper=true). After Gu1 face match approves, runs RENAPER biometric (validate-dniwith selfie) and data (DNI + trΓ‘mite). RequiresdocumentNumber,gender, andpersonalNumber(or entity fallback for DNI/gender). Response addsresponseDoubleChecks.renaper(including nestedrenaperBiometricwhen biometric check runs).POST /api/kyc/id-verification: same flag; after OCR approval runs RENAPER data check only (fields fromextractedData). Failed checks setstatustodeclinedand add RENAPER codes towarnings.- Org RENAPER credentials required (same as session KYC). Use HTTP timeout β₯ 60s for face-match with double-check.
KYT β separate status-change vs field-update triggers
PATCH β¦/changeStatusnow runs rules/matrices with triggerstatus_changed(trigger_transaction_status_changed), notupdated.PATCH /transactions/{id}(metadata, deviceDetails, channel, reason) withexecuteRules=truestill usesupdated(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 onlyupdated/ Transaction updated no longer run on changeStatus.
Partial transaction update
PATCH /transactions/{id}andPATCH /transactions/external/{externalId}: updatemetadata(shallow merge β omitted keys are preserved),deviceDetails(shallow merge intodevice_details),channel(nullable), and/orreason(enum). Requirestransactions:edit.- Query
executeRules=trueoptionally re-runs KYT rules with triggerupdated(trigger_transaction_updated) β not status-change rules. - Emits audit
transaction_updatedand webhooktransaction.updatedwith achangesmap (includesdeviceDetailswhen patched).
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, ortax_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
entityIdso you can call List by Entity whenhasEventsis true. GET /events/user/entity/{entityId}/has-eventsremains supported (unchanged contract).
Session KYC β Device & IP analysis warnings
GET /api/kyc/validations/:id(and sync/webhook paths): the top-levelwarningsarray now mergesriskcodes fromdecision.ip_analyses[].warnings[](and legacydecision.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
omitWarningsonPOST /api/kyc/validationswhen auto-approvingin_reviewsessions.
warnings until the next sync; re-fetch or sync to backfill IP analysis codes on older rows.ID Verification β richer extractedData
POST /api/kyc/id-verificationand audit list/get now persist and return a broaderextractedDataobject: identity fields (personalNumber,taxNumber,placeOfBirth, β¦),providerStatus,warningMeta(e.g. duplicate session IDs), quality scores,extraFields,mrz,parsedAddress,barcodeswhen returned by the Gu1 ID Verification service.warningsremains a string array of risk codes for i18n; usewarningMetainsideextractedDatafor structured duplicate-session metadata.- External document image URLs and base64 are not returned; images you uploaded are available via ID Verification images.
debugProviderResponsemay appear only in non-production Gu1 API environments (sanitized verification payload, no images).
operational hours per entity (global)
- Entities: Optional root field
operationalHours(timezoneenum +weeklyslots). Stored inentities.operational_hours. Documented on Create entity and related entity endpoints. - Transactions:
transaction_time_zoneenum extended (Brazil zones). OptionaltimeZoneis independent of entityoperationalHours.transactedAt: stored as UTC; ISO withZunchanged for existing clients; optional local datetime +timeZoneconverts to UTC when both are sent. - Rules: New operators
outside_entity_operational_hoursandinside_entity_operational_hoursontransactedAtwith valueoriginordestination. RequiresoperationalHourson the linked entity.
timeZone on transactions
- Database: New nullable column
time_zoneontransactionswith enum typetransaction_time_zone(IANA values such asAmerica/Argentina/Buenos_Aires,UTC, etc.). Existing rows remainnull. - API: Optional
timeZoneonPOST /transactionsand batch create; returned onGET /transactions/{id}andGET /transactions/external/{externalId}asstring | null.
validateExistingEntity (transaction create)
POST /transactions: optionalvalidateExistingEntity(defaultfalse). Whentrue, every origin/destination identifier you send must resolve to an existing person/company; otherwise 400INVALID_ENTITY_REFERENCESand no row is created.- Batch endpoints: default remains
true. UsevalidateExistingEntity: falsefor permissive bulk import. - Legacy KYT
POST /legacy/kyt/verifyTransaction: same field in the Gu2 body.
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.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
- π± 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
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
- β 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
- β Complete sequence diagram showing full flow
- β Sandbox vs Production clarification
- β Duplicate entity handling with code examples
- β Expanded integrationCode documentation
- β 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
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
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