Customer Credit Checks

Reference for the customer_credit_checks resource. Requests follow the conventions in Requests and Responses; fields you receive and may write are filtered by your user's permissions, so responses can contain a subset of the fields below.

Operations

Not available as a standard REST operation for this resource: create, update, delete — such requests return 402 feature_not_enabled or 403 permission_denied (see the actions above for this resource's write path).

How it works

customer_credit_checks are the credit pulls and manually-entered scores on a customer or lead. A check's result columns (score, bureau response, printable report) come from the credit bureau, not from the client — so checks are not created with a plain POST. Two collection actions create them:

Both are gated by the Credit Reports permission at the customer's location (leads: the lead-side Credit Reports permission). Reading a check's score and printable report additionally requires Beacon Score - Full Control — without it those fields are simply absent from responses. Raw bureau request/response payloads are never returned by the API, and no score data is ever exposed to AI/MCP surfaces.

Running a live pull

Find the tenant's configured bureaus (and their types) with the credit bureaus catalog: GET /credit_bureaus.

The bureau subject (name, SSN, date of birth, current address) is built from the customer record — sensitive identity data never rides the API request. Optionally send previous addresses and per-bureau options:

curl -X POST "https://portal.securitytrax.com/acme/user/v4/customer_credit_checks/run" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "customer_id": 100,
        "credit_bureau_id": 3,
        "addresses": [
          {"address": "123 Main St", "city": "Provo", "state": "UT", "zip": "84601"}
        ]
      }
    }
  }'

Per-bureau options (rejected with a 422 if sent for a different bureau type):

On success you get 201 with the created check (score visible only with the confidential permission). Failure modes:

The duplicate-pull guard

Live pulls are billable per run, so run refuses when a check for the same customer and bureau was created within the last 24 hours — the 409 names the existing check id. This protects against accidental double-submission and automation retries. When the re-pull is intentional (e.g. the customer's SSN or address was just corrected), pass "force": true to run anyway. Only successful pulls trip the guard — a failed pull persists nothing, so retrying after a 422/502 is never blocked. The record action has no guard (manual entries cost nothing).

Recording a manual score

curl -X POST "https://portal.securitytrax.com/acme/user/v4/customer_credit_checks/record" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data": {"attributes": {"customer_id": 100, "score": "720", "transaction_id": "TU-8842107"}}}'

credit_bureau_id is optional: omitted, the score is attributed to the company's Manual Score Entry bureau (created automatically if missing). If supplied, it must be a manual-type bureau — recording a hand-keyed score against a live bureau is rejected, and running a live pull against the manual bureau is likewise rejected.

When a check is applied to the customer

"Applying" a check writes its score onto the customer record (beacon_score), points the customer at the check, and stores the bureau transaction id. Two independent rules decide this — both are exact parity with the v1 API and the SecurityTrax UI:

1. First-check rule (both actions): if the new check is the customer's only check, it is applied automatically. Later checks are not — the customer keeps whichever check was applied until one is applied explicitly in SecurityTrax.
2. Company auto-apply flag (live pulls only): when the company setting auto-apply credit check to customer is on, every successful pull is applied, first or not.

Manual record entries are only ever auto-applied by the first-check rule.

Reading checks

GET /customer_credit_checks?customer_id=100 lists a customer's checks (filters: customer_id, credit_bureau_id, created_at_from/created_at_to; sort: id, customer_id, created_at). GET /customer_credit_checks/{id} fetches one. The parent include also works: GET /customers/100?include=credit_checks. In every read shape the score and printable report require the confidential-beacon permission, and the raw bureau request/response payloads are never returned.

Fields

Fields are grouped by the permission that gates them. A group you may not view is absent from responses; a group you may not write is rejected with 422 when sent in a write.

Credit Check

View: customers — Credit Run at the record's location; leads — Lead Credit Run. Create: customers — Credit Run at the record's location; leads — Lead Credit Run.

Sensitive Result

View: customers — Cust Conf Beacon at the record's location; leads — Lead Conf Beacon.

Pagination

The list endpoint uses client-controlled offset pagination: ?page= (1-based) and ?per_page= (default 25, max 100). The response mirrors meta.pagination (page, per_page, total, last_page) and sends an RFC5988 Link header; follow rel="next" to walk pages. See Pagination.

Filters

The list endpoint accepts these query-param filters: customer_id, credit_bureau_id, created_at_from, created_at_to. An unsupported filter parameter returns 422. See Filtering collections for matching semantics.

Sorting

GET .../customer_credit_checks?sort= orders the list by: id, customer_id, created_at. Prefix a field with - for descending; comma-separate for tie-breakers. An unsupported field returns 422. See Sorting collections.

Related

• Requests and Responses — envelope, errors, pagination, and rate limits.
• Authentication — tokens and the Authorization header.