---
title: "Evaluate one customer synchronously"
method: POST
path: "/api/v1/evaluate"
tags: ["Evaluate"]
---

# Evaluate one customer synchronously

`POST /api/v1/evaluate`

## Request

- Base URL: `https://slopeai.slopepay.com`
- URL: `https://slopeai.slopepay.com/api/v1/evaluate`
- Auth: HTTP bearer

Stores the customer's accounts, balances, and transactions (same as POST /batch), then runs enrichment and evaluation inline and returns the evaluation. The evaluation uses the customer's full stored history, not only the transactions in this request. If it does not finish within 55 seconds, returns 504 EVALUATION_TIMEOUT with a job_id while processing continues; retry with the same Idempotency-Key to get the result.

## Headers

- `Idempotency-Key` string: Optional idempotency key for safely retrying an evaluation. Reusing the same key with an identical request body returns the original evaluation (or EVALUATION_IN_PROGRESS while it is still running) without re-running it; reusing it with a different body returns IDEMPOTENCY_MISMATCH (400). Keys expire after a TTL.

## Request body

- SyncEvaluateRequest: `include_score` is no longer supported; use `product`.
  - `customer` Customer, required
    - `customer_id` string, required: Unique customer identifier in the client's system
    - `type` 'business' | 'individual' | 'nonprofit': Type of customer
    - `first_name` string
    - `last_name` string
    - `business_name` string
  - `accounts` Account[]
    - `account_id` string, required
    - `type` 'depository' | 'liability': Type of account. When omitted, new accounts default to depository and existing accounts keep their stored type.
    - `number_mask` string, nullable
    - `name` string, nullable
  - `balances` AccountBalance[]
    - `account_id` string, required: Identifier for the account this balance belongs to
    - `date` string, date-time, required: Timestamp at which this balance was observed from the provider
    - `current` integer, nullable: Current balance in cents as of the observed timestamp
    - `available` integer, nullable: Available balance in cents as of the observed timestamp
    - `currency` string
  - `transactions` Transaction[]: Up to 10000 transactions; larger requests are rejected with REQUEST_TOO_LARGE (400) and should use POST /batch. Transactions are upserted by transaction_id; when a transaction_id repeats, the last occurrence wins.
    - `transaction_id` string, required
    - `account_id` string, required
    - `description` string, required
    - `amount` integer, required: Signed amount in cents. Positive = outflow (money leaving the account); negative = inflow (money entering the account).
    - `date` string, date-time, required: Posting date for the transaction
    - `authorized_date` string, date-time, nullable
    - `currency` string
  - `product` 'ATTRIBUTES' | 'SCORE' | 'ATTRIBUTES_AND_SCORE', required: What an EVALUATE returns: cash flow attributes (features, monthly financials, and recurring cash flows), the Slope Score with its reasons, or both

## Response `200`

Evaluation for the customer

- SyncEvaluateResponse
  - `id` string, required
  - `customer_id` string, required
  - `as_of` string, date-time, required: Timestamp at which this evaluation was computed
  - `data_window_start` string, nullable, required: Start date of the data window used for evaluation
  - `data_window_end` string, nullable, required: End date of the data window used for evaluation
  - `model_version` string, nullable, required: Version of the evaluation model used
  - `features_version` string, nullable, required: Version of the features schema
  - `product` 'ATTRIBUTES' | 'SCORE' | 'ATTRIBUTES_AND_SCORE', required: The product this evaluation was requested with; it decides which of the fields below are returned
  - `slope_score` SlopeScore, nullable, required: Slope Score and reasons. Null when product is ATTRIBUTES.
    - `score` number, nullable, required
    - `version` string, nullable, required
    - `reasons` ScoreReason[], required
      - `code` string, required
      - `description` string, required
  - `features` object, nullable, required: Cash flow attributes used for evaluation. Null when product is SCORE.
  - `financials` MonthlyFinancials[], nullable: Monthly financials. Null when product is SCORE.
    - `month` string, required
    - `income_statement` object
    - `cashflow_statement` object
  - `recurring_cashflows` RecurringCashflow[], nullable: Recurring cash flow groupings derived from enriched transactions across accounts for this customer. Null when product is SCORE.
    - `counterparty` string, required
    - `start_date` string, required
    - `end_date` string, required
    - `transaction_count` integer, required
    - `total_amount` integer, required
    - `avg_amount` integer, required
    - `is_recurring` boolean, required
    - `recurrence_strength` number, nullable
    - `periodicity_days` number, nullable
    - `periodicity` string, nullable
    - `next_expected_transaction` string, nullable
    - `status` string, required
    - `example_transaction` string, nullable
  - `job_id` string, required

## Other responses

- `400`: Invalid request. Causes include malformed JSON (INVALID_JSON), request schema validation failures (SCHEMA_VALIDATION), the customer failing validation such as missing accounts, balances, or transactions (VALIDATION_FAILED), more than 10,000 transactions (REQUEST_TOO_LARGE; use POST /batch), and reusing an Idempotency-Key with a different body (IDEMPOTENCY_MISMATCH).
- `401`: Missing or invalid API key
- `409`: An earlier request with the same Idempotency-Key is still being evaluated (EVALUATION_IN_PROGRESS)
- `413`: Request JSON body exceeds the maximum byte size (REQUEST_TOO_LARGE); split it into smaller requests
- `500`: Unexpected server error
- `502`: Evaluation ran but failed (EVALUATION_FAILED)
- `504`: Evaluation did not finish within the deadline and is still running (EVALUATION_TIMEOUT)

---

[API](https://skmtc.dev/slopepay/apis/slopeai-api.md) - [All operations](https://skmtc.dev/slopepay/apis/slopeai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/slopepay/apis/slopeai-api/revisions/c3a6761e9639?raw)