> ## Documentation Index > Fetch the complete documentation index at: https://docs.synctera.com/llms.txt > Use this file to discover all available pages before exploring further. # External Scores > External scores let you inject custom, externally sourced risk scores into Synctera's managed Customer Risk Rating (CRR) system. ## Overview Synctera continuously computes a [Customer Risk Rating (CRR)](/reference/listcrr) 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: * Created a [personal customer](/docs/create-a-personal-customer) or [business customer](/docs/create-a-business) You should also be familiar with: * [Need to Know — Environments](/reference/need-to-know#environments) * [Need to Know — Authentication](/reference/need-to-know#authentication) ## The external score object An external score contains the following key fields: | Field | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `id` | Unique identifier (read-only, assigned on creation). | | `resource_id` | **Required.** The `customer_id` or `business_id` to assign the score to. | | `resource_type` | **Required.** The type of resource the score applies to: `CUSTOMER` or `BUSINESS`. | | `score` | **Required.** An externally sourced risk score (integer, 0–100), used directly as a condition weight in the CRR calculation. | | `high_risk_override` | When `true`, forces the computed CRR rating to high regardless of the numeric score. Defaults to `false`. | | `description` | Optional narrative explaining the score rationale. | | `metadata` | Optional free-form structured metadata supplied by the operator or external system. | | `tenant` | Tenant id containing the resource (relevant for multi-workspace FinTechs). | | `creation_time` | When the record was created (read-only). | | `last_updated_time` | When the record was last updated (read-only). | ```json theme={"system"} { "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](/reference/listexternalscores) for the full request and response schemas. ## Managing external scores Use [POST /v0/crr/external\_scores](/reference/createexternalscore). At minimum you must provide a `resource_id`, a `resource_type`, and a `score`. **Example: Score from a rules engine** A FinTech's rules engine produces a risk score for a customer and pushes it into Synctera so it contributes to the managed CRR rating: ```shell theme={"system"} 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 indicator** During an ongoing investigation, operational staff force the customer's rating to high regardless of the numeric score: ```shell theme={"system"} 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`: ```json theme={"system"} { "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" } ``` Use [GET /v0/crr/external\_scores](/reference/listexternalscores) to list scores. You can filter by `resource_id` and `resource_type`. ```shell theme={"system"} 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}](/reference/getexternalscore): ```shell theme={"system"} curl \ -X GET \ -H "Authorization: Bearer $apikey" \ "https://api.synctera.com/v0/crr/external_scores/7503cd8a-903b-4fee-aa54-da3dc71f4124" ``` Use [PATCH /v0/crr/external\_scores/\{external\_score\_id}](/reference/updateexternalscore) 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: ```shell theme={"system"} 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" } }' ``` 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}](/reference/deleteexternalscore). The score stops contributing to the CRR calculation. ```shell theme={"system"} 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: * [List external scores](/reference/listexternalscores) * [Create an external score](/reference/createexternalscore) * [Get an external score](/reference/getexternalscore) * [Update an external score](/reference/updateexternalscore) * [Delete an external score](/reference/deleteexternalscore)