Credit Card Decisions

Score an application for a revolving credit card product. Uses cash-flow underwriting to assign a credit limit and a tiered purchase APR. Returns a Reg Z (Schumer box) disclosure, a counter-offer with a lower limit, or a decline with ECOA reason codes.

Embedded product

Credit cards are a revolving, embedded product. Unlike installment loans, there is no fixed term or monthly payment — AltFiScore assigns a credit limit and APR tier. The consumer relationship is managed in your own card platform after approval.

Create a decision

POST/v1/decisions/credit-card

Request body

Field	Type	Description
`consumer`Required	`object`	Identifies the consumer. See Consumer object below. Either consumer_id (for returning customers) OR full PII fields (for new consumers).
`product`Required	`object`	The card product and requested limit. See Product object below.

Consumer object

Field	Type	Description
`consumer_id`	`uuid`	UUID of an existing consumer in your tenant. Skip the rest of the consumer fields if provided.
`first_name`	`string`	Required for new consumers.
`last_name`	`string`	Required for new consumers.
`email`	`string`	Required for new consumers. Used for verification flows.
`phone`	`string`	E.164 format. Used for SMS verification when KYC tier is enhanced/hard.
`dob`	`string`	ISO 8601 date (YYYY-MM-DD). Required for new consumers.
`ssn_last4`	`string`	Last 4 digits of SSN. Required for enhanced/hard KYC. Encrypted at rest.
`address`	`object`	Mailing address. line1, city, state, zip required for new consumers.

Product object

Field	Type	Description
`card_program`Required	`string`	Your card program identifier (e.g., cashback_rewards, secured_starter, travel). Maps to your configured product policy.
`requested_limit`	`decimal`	The credit limit the applicant requested. AltFiScore may approve a lower limit based on risk grade. If omitted, AltFiScore assigns a limit.
`currency`Required	`string`	ISO 4217 currency code. Currently only USD is supported.

Example request

Request body

{
  "consumer": {
    "first_name": "Marcus",
    "last_name": "Bello",
    "email": "marcus@example.com",
    "phone": "+15554443322",
    "dob": "1990-11-05",
    "ssn_last4": "2255",
    "address": {
      "line1": "17 Rivera Ct",
      "city": "Miami",
      "state": "FL",
      "zip": "33101"
    }
  },
  "product": {
    "card_program": "cashback_rewards",
    "requested_limit": 5000.00,
    "currency": "USD"
  }
}

Response

The response status depends on the KYC tier AltFiScore assigns. Card decisions typically require enhanced KYC. Enhanced and hard-tier decisions return needs_consumer_action with a URL the consumer must visit to complete verification.

Approved

Status complete with outcome approved. The response includes the assigned approved_limit, tiered APRs, and a full reg_z_disclosure (Schumer box).

200 OK · approved

{
  "decision_id": "d45e6f78-9a0b-4c1d-8e2f-3a4b5c6d7e8f",
  "application_id": "d45e6f78-9a0b-4c1d-8e2f-3a4b5c6d7e8f",
  "status": "complete",
  "kyc_tier": "enhanced",
  "kyc_status": "matched",
  "outcome": "approved",
  "score": 745,
  "risk_grade": "B",
  "approved_limit": "5000.00",
  "currency": "USD",
  "purchase_apr": "21.99",
  "cash_advance_apr": "27.99",
  "penalty_apr": "29.99",
  "annual_fee": "0.00",
  "reg_z_disclosure": {
    "purchase_apr": "21.99",
    "cash_advance_apr": "27.99",
    "penalty_apr": "29.99",
    "grace_period_days": 25,
    "annual_fee": "0.00",
    "min_payment_pct": "2.0"
  },
  "decline_reasons": [],
  "expires_at": "2026-05-15T20:30:20.566665Z"
}

Counter-offer (referred)

When the requested limit exceeds the maximum for the assigned risk grade, AltFiScore returns outcome referred with a counter_offer at a lower limit. The consumer can accept the adjusted limit and APR.

200 OK · counter-offer

{
  "decision_id": "e56f7a89-...",
  "application_id": "e56f7a89-...",
  "status": "complete",
  "outcome": "referred",
  "score": 670,
  "risk_grade": "C",
  "counter_offer": {
    "is_viable": true,
    "offered_limit": "2000.00",
    "purchase_apr": "27.99",
    "annual_fee": "0.00",
    "reason": "Your requested limit of $5,000 exceeds the maximum for Grade C applicants (max $2,000)."
  },
  "decline_reasons": []
}

Declined

Status complete with outcome declined. The decline_reasons array contains ECOA-compliant codes. See compliance for guidance on adverse action handling.

200 OK · declined

{
  "decision_id": "f67a8b90-...",
  "application_id": "f67a8b90-...",
  "status": "complete",
  "outcome": "declined",
  "score": 610,
  "risk_grade": "D",
  "decline_reasons": [
    { "code": "AA-01", "reason": "Insufficient cash flow stability over the last 90 days." },
    { "code": "AA-11", "reason": "Recent history of overdrafts or returned payments." }
  ]
}

A decline is still a 200

The HTTP status indicates whether the API call succeeded, not whether the consumer was approved. A successfully-evaluated decline is HTTP 200 with outcome: "declined". See the errors page for genuine error cases.

Response fields

Field	Type	Description
`decision_id`	`uuid`	Unique identifier for this decision. Store for reconciliation and later lookup.
`application_id`	`uuid`	Identifier for the underlying application. Typically equals decision_id for first-time decisions.
`status`	`string`	complete or needs_consumer_action.
`kyc_tier`	`string`	soft, enhanced, or hard. Indicates the verification depth applied.
`kyc_status`	`string`	matched, pending, or skipped.
`outcome`	`string`	approved, declined, or referred. null when status is needs_consumer_action.
`score`	`integer`	AltFiScore from 300 to 1000.
`risk_grade`	`string`	Letter grade A+ through D derived from the score.
`approved_limit`	`decimal`	String. The credit limit AltFiScore assigned. May be less than requested.
`purchase_apr`	`decimal`	String. The revolving purchase APR as a percentage, tiered by risk grade.
`cash_advance_apr`	`decimal`	String. The cash advance APR as a percentage.
`penalty_apr`	`decimal`	String. The penalty APR applied after a qualifying late payment.
`annual_fee`	`decimal`	String. The annual fee for the assigned product tier.
`reg_z_disclosure`	`object`	Reg Z Schumer box disclosure block ready to display to the applicant.
`counter_offer`	`object`	Present when outcome is referred. Contains adjusted limit, APR, and reason.
`decline_reasons`	`array`	Array of { code, reason } objects. Populated when outcome is declined or referred.
`expires_at`	`timestamp`	ISO 8601 timestamp. The offer expires at this time.

Poll a decision

GET/v1/decisions/credit-card/{decision_id}

Returns the current state of a previously-created decision. Idempotent and safe to call repeatedly. Recommended polling interval: 2–3 seconds.

Poll a pending decision

curl 'https://api.altfiscore.com/v1/decisions/credit-card/d45e6f78-9a0b-4c1d-8e2f-3a4b5c6d7e8f' \
  -H 'Authorization: Bearer altfi_test_YOUR_KEY'

Use idempotency

Both POST and GET endpoints are safe to retry. The POST endpoint with the same Idempotency-Key returns the cached decision. The GET endpoint is naturally idempotent.

Errors

Returns standard HTTP error codes. The full catalog is in the errors reference. Most common errors for this endpoint:

400 invalid_request — required field missing (e.g., product.card_program)
401 invalid_api_key — bad or missing API key
409 idempotency_conflict — same idempotency key with a different body
422 unprocessable_entity — request is well-formed but the card_program is not configured for your tenant

Next steps

Review the credit card product page for APR tiers and limit assignment
Set up idempotent retries
Handle declines with the compliance guide