Skip to main content

​
Overview

Synctera continuously computes a Customer Risk Rating (CRR) for every customer and business. The rating is driven by a set of platform conditions, each contributing a weighted score. In most cases these built-in conditions capture the risk signals you need — but banks and FinTechs often maintain their own risk data outside of Synctera that should influence the rating. External scores give you a controlled way to feed that data in. An external score tells the platform: “for this customer (or business), apply this externally sourced risk score as an input to the CRR calculation.” The score is used directly as a condition weight, so it flows through the same rating machinery as Synctera’s native conditions. Key characteristics:
  • Scoped — each external score is tied to a resource_id (a customer_id or business_id) and a resource_type (CUSTOMER or BUSINESS).
  • Weighted — the score (an integer from 0–100) is used directly as a condition weight in the CRR calculation.
  • Overridable — set high_risk_override to true to force the resource’s computed CRR rating to high regardless of the numeric score.
  • Auditable — an optional description and free-form metadata object let you record why the score was applied and where it came from.

​
When to use external scores

Common scenarios include:
  • Risk / rules engine integration — A FinTech runs its own transaction-monitoring or rules engine and pushes the resulting risk scores into Synctera so they factor into the managed CRR rating.
  • Compliance-driven high-risk indicators — Operational staff flag a customer during an ongoing compliance investigation. Creating an external score with high_risk_override set to true forces the customer’s rating to high while the review is underway.
  • Third-party risk data — Scores sourced from an external vendor (fraud, sanctions, credit) are injected so they contribute to the overall rating alongside Synctera’s built-in conditions.

​
Prerequisites

This guide assumes you have: You should also be familiar with:

​
The external score object

An external score contains the following key fields:
FieldDescription
idUnique identifier (read-only, assigned on creation).
resource_idRequired. The customer_id or business_id to assign the score to.
resource_typeRequired. The type of resource the score applies to: CUSTOMER or BUSINESS.
scoreRequired. An externally sourced risk score (integer, 0–100), used directly as a condition weight in the CRR calculation.
high_risk_overrideWhen true, forces the computed CRR rating to high regardless of the numeric score. Defaults to false.
descriptionOptional narrative explaining the score rationale.
metadataOptional free-form structured metadata supplied by the operator or external system.
tenantTenant id containing the resource (relevant for multi-workspace FinTechs).
creation_timeWhen the record was created (read-only).
last_updated_timeWhen the record was last updated (read-only).
{
  "id": "7503cd8a-903b-4fee-aa54-da3dc71f4124",
  "resource_id": "5f4ff599-7c29-4f69-a3d9-e103e151afbd",
  "resource_type": "CUSTOMER",
  "score": 75,
  "high_risk_override": false,
  "description": "Score fed from FinTech rules engine.",
  "metadata": {
    "source": "rules-engine",
    "model_version": "2.3.1"
  },
  "tenant": "abcdef_ghijkl",
  "creation_time": "2024-01-01T00:00:00.000Z",
  "last_updated_time": "2024-01-01T00:00:00.000Z"
}
See the API reference for the full request and response schemas.

​
Managing external scores

1

Create an external score

Use POST /v0/crr/external_scores. At minimum you must provide a resource_id, a resource_type, and a score.Example: Score from a rules engineA FinTech’s rules engine produces a risk score for a customer and pushes it into Synctera so it contributes to the managed CRR rating:
curl \
  -X POST \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  https://api.synctera.com/v0/crr/external_scores \
  --data-binary '
  {
    "resource_id": "5f4ff599-7c29-4f69-a3d9-e103e151afbd",
    "resource_type": "CUSTOMER",
    "score": 75,
    "description": "Score fed from FinTech rules engine.",
    "metadata": {
      "source": "rules-engine",
      "model_version": "2.3.1"
    }
  }'
Example: Compliance-driven high-risk indicatorDuring an ongoing investigation, operational staff force the customer’s rating to high regardless of the numeric score:
curl \
  -X POST \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  https://api.synctera.com/v0/crr/external_scores \
  --data-binary '
  {
    "resource_id": "5f4ff599-7c29-4f69-a3d9-e103e151afbd",
    "resource_type": "CUSTOMER",
    "score": 90,
    "high_risk_override": true,
    "description": "Manual escalation - open compliance investigation (case #4821)."
  }'
The response includes the system-generated id, creation_time, and last_updated_time:
{
  "id": "7503cd8a-903b-4fee-aa54-da3dc71f4124",
  "resource_id": "5f4ff599-7c29-4f69-a3d9-e103e151afbd",
  "resource_type": "CUSTOMER",
  "score": 90,
  "high_risk_override": true,
  "description": "Manual escalation - open compliance investigation (case #4821).",
  "tenant": "abcdef_ghijkl",
  "creation_time": "2024-05-31T14:22:08.123Z",
  "last_updated_time": "2024-05-31T14:22:08.123Z"
}
2

List and review external scores

Use GET /v0/crr/external_scores to list scores. You can filter by resource_id and resource_type.
curl \
  -X GET \
  -H "Authorization: Bearer $apikey" \
  "https://api.synctera.com/v0/crr/external_scores?resource_id=5f4ff599-7c29-4f69-a3d9-e103e151afbd&resource_type=CUSTOMER"
To retrieve a single external score by ID, use GET /v0/crr/external_scores/{external_score_id}:
curl \
  -X GET \
  -H "Authorization: Bearer $apikey" \
  "https://api.synctera.com/v0/crr/external_scores/7503cd8a-903b-4fee-aa54-da3dc71f4124"
3

Update an external score

Use PATCH /v0/crr/external_scores/{external_score_id} to modify an existing score. You can update the score, high_risk_override, description, and metadata fields.For example, to raise a customer’s score after a fresh evaluation from the rules engine:
curl \
  -X PATCH \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  https://api.synctera.com/v0/crr/external_scores/7503cd8a-903b-4fee-aa54-da3dc71f4124 \
  --data-binary '
  {
    "score": 82,
    "description": "Re-scored after new transaction activity.",
    "metadata": {
      "source": "rules-engine",
      "model_version": "2.4.0"
    }
  }'
4

Delete an external score

When an external score is no longer relevant — for example, once a compliance investigation is closed — remove it with DELETE /v0/crr/external_scores/{external_score_id}. The score stops contributing to the CRR calculation.
curl \
  -X DELETE \
  -H "Authorization: Bearer $apikey" \
  "https://api.synctera.com/v0/crr/external_scores/7503cd8a-903b-4fee-aa54-da3dc71f4124"

​
Best practices

External scores directly influence a customer’s managed risk rating, and high_risk_override bypasses the numeric calculation entirely. Use them deliberately and always with a clear, documented rationale.
  • Record the source — Use description and metadata to capture where the score came from (rules engine, vendor, manual escalation) so a compliance reviewer can trace it later.
  • Keep scores fresh — When your external system re-evaluates a resource, PATCH the existing score rather than accumulating stale records.
  • Reserve high_risk_override for genuine escalations — Because it forces a high rating regardless of the numeric score, limit it to situations like active investigations, and remove it once the underlying condition clears.
  • Clean up when no longer relevant — Delete scores tied to time-bounded events (e.g., a closed case) so they don’t keep affecting the rating after the fact.
  • Review regularly — Use the list endpoint with filters to audit the external scores currently applied to a customer or business.

​
API reference

See the full External Scores API reference for request/response schemas and all available parameters: