--- updatedAt: 2026-04-21T04:46:34.000Z agentTools: projectIndex: https://developer.alloy.com/public/llms.txt --- # Runs an evaluation Given a workflow specified by the header, the API will run an evaluation with the provided payload. Alloy's API is dynamic, and thus the input parameters vary depending on which services are run and how the workflow is configured. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Alloy API", "version": "1.0.0", "description": "hey hey hey, it's the Alloy API!" }, "servers": [ { "url": "https://sandbox.alloy.co/v1", "description": "Sandbox endpoint" } ], "security": [ { "oauth2": [] }, { "basic": [] } ], "tags": [ { "name": "Evaluations", "description": "Evaluations are a core part of the Alloy world. In order to onboard a customer you can run an evaluation under a specific workflow, and that will create both the evaluation and, in most cases, the entity for that customer." } ], "paths": { "/evaluations": { "post": { "summary": "Runs an evaluation", "description": "Given a workflow specified by the header, the API will run an evaluation with the provided payload. Alloy's API is dynamic, and thus the input parameters vary depending on which services are run and how the workflow is configured.\n", "tags": [ "Evaluations" ], "parameters": [ { "in": "header", "name": "Authorization", "schema": { "type": "string", "description": "Basic authorization header per the OAuth Client Authorization Header standard.\n\nThe format is `Basic `, where `` is the base64 encoding of the string `token:secret` (check [Authentication Guide](https://developer.alloy.com/public/docs/authentication-guide) for details).\n" } }, { "in": "header", "name": "alloy-workflow-token", "schema": { "type": "string", "description": "If you have migrated to the new API Key Settings page and are using account-level API keys for authentication, this header is required to specify which workflow to use for the evaluation.\n\nIf you have not migrated yet, this header is optional, as the workflow will be determined by the Authorization header using workflow_token.\n" } }, { "in": "header", "name": "alloy-entity-token", "schema": { "type": "string", "description": "If running an additional evaluation for an existing entity - the existing entity token can be provided to connect the new evaluation to the entity.\n" } }, { "in": "header", "name": "alloy-external-entity-id", "schema": { "type": "string", "description": "A string to identify the entity created by the evaluation in your system.\n" } }, { "in": "header", "name": "alloy-parent-entity-token", "schema": { "type": "string", "description": "A token of an entity to be used as a parent entity.\n" } }, { "in": "header", "name": "alloy-entity-type", "schema": { "description": "For transactions workflows, specifies whether the entity associated with\nthe evaluation is a `business` or `person` entity. Defaults to `person`.\n", "type": "string", "enum": [ "business", "person" ] } }, { "in": "header", "name": "alloy-hydrate-counterparty-data", "schema": { "type": "boolean", "description": "Optional boolean value, required to be true for using counterparty sanction screening in a transaction workflow.\n" } }, { "in": "header", "name": "alloy-hydrate-entity-data", "schema": { "type": "boolean", "description": "Optional boolean value, required to be true for using source entity sanction screening in a transaction workflow.\n" } }, { "$ref": "#/components/parameters/AlloySandboxPersonaToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Evaluation Body", "$ref": "#/components/schemas/EvaluationBody" }, { "title": "Transaction Evaluation Body", "$ref": "#/components/schemas/TransactionEvaluationBody" } ] } } } }, "x-samples-languages": [ "shell" ], "responses": { "200": { "description": "Evaluation missing required inputs", "content": { "application/json": { "schema": { "type": "object", "properties": { "status_code": { "type": "string" }, "error": { "type": "object" }, "timestamp": { "type": "number" }, "evaluation_token": { "type": "string" }, "entity_token": { "type": "string" }, "application_token": { "type": "string" }, "application_version_id": { "type": "number" }, "required": { "type": "array", "description": "The required fields for this workflow", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "name_first" }, "type": { "type": "string", "example": "string" }, "description": { "type": "string", "example": "First name" }, "regex": { "type": "string", "example": "^[^d]*$" }, "properties": { "type": "object" } } } }, "optional": { "type": "array", "description": "The optional fields for this workflow", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "email_address" }, "type": { "type": "string", "example": "string" }, "description": { "type": "string", "example": "Email address" }, "regex": { "type": "string", "example": "" }, "properties": { "type": "object" } } } } } } } } }, "201": { "description": "Evaluation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Evaluation" } } } } } } } }, "components": { "securitySchemes": { "basic": { "type": "http", "description": "HTTP basic authorization using a workflow token and secret", "scheme": "basic" }, "oauth2": { "type": "oauth2", "description": "Oauth2 using a workflow token and secret to generate a bearer token", "flows": { "clientCredentials": { "tokenUrl": "/oauth/bearer", "scopes": {} } } } }, "schemas": { "AccountSnapshot": { "required": [ "timestamp" ], "properties": { "timestamp": { "description": "ISO 8601 timestamp of the account snapshot.", "type": "string", "format": "date" }, "meta": { "description": "JSON object with any meta information related to the account snapshot.", "type": "object" }, "details": { "description": "JSON object with any details related to the account snapshot.", "type": "object", "properties": { "status": { "type": "string", "nullable": true, "enum": [ null, "Active", "Deactivated", "Frozen", "Pending", "Inactive" ] }, "status_detail": { "type": "string" }, "loan_credit_limit": { "type": "integer" }, "interest_rate": { "type": "number" }, "original_interest_rate": { "type": "number" }, "original_amount": { "type": "integer" }, "ach_push_limit": { "type": "integer" }, "ach_pull_limit": { "type": "integer" }, "name_first": { "type": "string" }, "name_last": { "type": "string" }, "email_address": { "type": "string" }, "phone_number": { "type": "string" }, "mailing_address_line1": { "type": "string" }, "mailing_address_line2": { "type": "string" }, "mailing_address_city": { "type": "string" }, "mailing_address_state": { "type": "string" }, "mailing_address_postal_code": { "type": "string" }, "mailing_address_country_code": { "description": "3-character country code (e.g. \"USA\")", "type": "string" }, "primary_address_line1": { "type": "string" }, "primary_address_line2": { "type": "string" }, "primary_address_city": { "type": "string" }, "primary_address_state": { "type": "string" }, "primary_address_postal_code": { "type": "string" }, "primary_address_country_code": { "description": "3-character country code (e.g. \"USA\").", "type": "string", "maxLength": 3 } } }, "account_view": { "description": "JSON object", "type": "object", "properties": { "account_balance": { "description": "Account balance in cents.", "type": "integer" }, "date_last_activity": { "description": "ISO 8601 timestamp of last activity.", "type": "string" }, "is_good_standing": { "type": "boolean" }, "past_due_days": { "type": "integer" } } } } }, "BankAccountBody": { "properties": { "bank_account_token": { "description": "Alloy-generated unique identifier for the account", "type": "string", "readOnly": true }, "external_account_id": { "description": "Unique identifier associated with the account. At least one of `external_account_id` or `account_number` must be provided.", "type": "string", "maxLength": 60 }, "account_number": { "description": "Bank account number. At least one of `account_number` or `external_account_id` must be provided.", "type": "string" }, "account_class": { "description": "Allowed values are (`\"deposit\"`, `\"credit\"`, `\"brokerage\"`).", "type": "string", "enum": [ "deposit", "credit", "brokerage" ] }, "account_name": { "description": "Name of the account.", "type": "string" }, "routing_number": { "description": "Routing number associated with the account.", "type": "string" }, "account_type": { "description": "Allowed values are (`\"merchant account\"`, `\"person\"`, `null`).", "type": "string", "enum": [ "merchant account", "person" ], "nullable": true }, "is_linked_account": { "description": "Determines whether the account is a funding source or linked account.", "type": "boolean", "nullable": true }, "link_timestamp": { "description": "ISO 8601 date. Required when `is_linked_account` is true. Cannot be future-dated.", "type": "string", "format": "date-time", "nullable": true }, "unlink_timestamp": { "description": "ISO 8601 date. Cannot be future-dated.", "type": "string", "format": "date-time", "nullable": true }, "opening_date": { "description": "UTC/ISO dates both accepted. Strings are converted to ISO timestamps. Date the account was opened.", "type": "string", "format": "date", "nullable": true }, "country_code": { "type": "string", "description": "2-character ISO Code (mainly used for merchant accounts).", "maxLength": 2, "nullable": true }, "account_snapshot": { "type": "object", "description": "JSON object. Account snapshots are upserted according to their `timestamp` value. If a snapshot already exists for a given account and timestamp value, it will be updated; otherwise, a new account snapshot will be created.", "$ref": "#/components/schemas/AccountSnapshot" }, "product_code": { "description": "Identifier of the product name.", "type": "string", "nullable": true }, "product_name": { "description": "Name of the product associated with the account.", "type": "string", "nullable": true }, "product_number": { "type": "string", "description": "Product number that corresponds to the product_name associated with the account.", "nullable": true }, "maturity_date": { "description": "UTC/ISO dates are both accepted. Strings are converted to ISO timestamps. Date on which the final payment is due on a loan or other financial instrument, such as a bond or term deposit, at which point the principal is due to be paid.", "type": "string", "format": "date", "nullable": true }, "closing_date": { "description": "UTC/ISO dates both accepted. Strings are converted to ISO timestamps. Date the account was closed.", "type": "string", "format": "date", "nullable": true }, "cif_number": { "type": "string", "description": "Unique identifier used by bank cores to refer to a customer.", "nullable": true }, "card_network": { "type": "string", "description": "Card network of the card that was used in this transaction.", "maxLength": 20, "nullable": true }, "expiration_date": { "type": "string", "nullable": true }, "tokenization_method": { "type": "string", "description": "method of tokenization used to anonymize account information.", "maxLength": 20, "nullable": true }, "merchant_category_code": { "type": "string", "description": "The merchant category code (MCC) is used to classify a business by the purposes it serves or the products it sells.", "maxLength": 20, "nullable": true }, "name_on_card": { "type": "string", "description": "Name on the card used in this transaction.", "maxLength": 100, "nullable": true }, "account_number_last4": { "type": "string", "description": "Last four digits of account number", "maxLength": 4, "nullable": true }, "avs": { "type": "string", "description": "Verifies the numeric portions of the address against the billing address.", "maxLength": 20, "nullable": true }, "currency": { "type": "string", "description": "ISO-4217 currency code.", "maxLength": 4, "nullable": true }, "meta": { "description": "JSON object with any meta information related to the account", "type": "object", "nullable": true } }, "example": { "external_account_id": "test-account-001", "account_class": "deposit", "entities": [ { "external_entity_id": "entity-01", "account_holder_type": "primary" } ], "account_snapshot": { "timestamp": "2022-03-21T21:50:07.623Z", "details": { "status": "Active" } } } }, "Evaluation": { "properties": { "status_code": { "type": "string" }, "error": { "type": "object" }, "timestamp": { "type": "number" }, "evaluation_token": { "type": "string" }, "entity_token": { "type": "string" }, "application_token": { "type": "string" }, "application_version_id": { "type": "number" }, "summary": { "type": "object", "properties": { "result": { "type": "string" }, "score": { "type": "number" }, "tags": { "type": "array", "items": { "type": "string" } }, "outcome_reasons": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "nullable": true, "enum": [ "adverse_action", null ] } } } }, "outcome": { "type": "string" }, "services": { "type": "object", "description": "A map of service names to their execution statuses. Keys are dynamic and represent services in the Workflow.", "additionalProperties": { "type": "string", "enum": [ "executed", "not_executed", "cached", "failed" ] } }, "custom_fields": { "type": "object", "description": "A map of custom field names to their values. Keys are dynamic and represent input attributes defined in the Workflow." }, "models": { "type": "object", "description": "A map of output attribute names to their values. Keys are dynamic and represent output attributes defined in the Workflow." } } }, "supplied": { "type": "object" }, "formatted": { "type": "object" }, "matching": { "type": "object" }, "diligence": { "type": "object" }, "related_data": { "type": "object" }, "raw_responses": { "type": "object" }, "formatted_responses": { "type": "object" }, "audit_archive": { "type": "object" }, "warnings": { "type": "object", "description": "Warnings about the evaluation, such as missing data that resulted in a partial response.", "properties": { "blocked_actions": { "type": "array", "description": "A list of actions (tags, services) that were blocked during the evaluation due to missing data or other issues.", "items": { "type": "object", "properties": { "blocked": { "type": "object", "properties": { "action_name": { "type": "string", "description": "The name of the action that was blocked." }, "action_type": { "type": "string", "description": "The type of the action that was blocked." } } }, "blocking": { "type": "object", "properties": { "action_name": { "type": "string", "description": "The name of the service that caused the block." }, "attribute_name": { "type": "string", "description": "The specific attribute that caused the block." } } } } } } } } } }, "EvaluationBody": { "type": "object" }, "AccountBodyWithExternalAccountId": { "required": [ "external_account_id" ] }, "AccountBodyWithAccountNumber": { "required": [ "account_number" ] }, "SourceAccount": { "description": "The account that is being evaluated. Typically this is the account that is owned by your organization.\nThe body must contain either an `external_account_id` or `account_number`.\n", "allOf": [ { "$ref": "#/components/schemas/BankAccountBody" } ], "anyOf": [ { "$ref": "#/components/schemas/AccountBodyWithExternalAccountId" }, { "$ref": "#/components/schemas/AccountBodyWithAccountNumber" } ] }, "DestinationAccount": { "description": "The counterparty account that is interacting with the `source_account`-- for example, a merchant account.\nThe body must contain either an `external_account_id` or `account_number`.\n", "allOf": [ { "$ref": "#/components/schemas/BankAccountBody" } ], "anyOf": [ { "$ref": "#/components/schemas/AccountBodyWithExternalAccountId" }, { "$ref": "#/components/schemas/AccountBodyWithAccountNumber" } ], "properties": { "name_first": { "type": "string" }, "name_last": { "type": "string" }, "birth_date": { "description": "YYYY-MM-DD", "type": "string" }, "address_line_1": { "type": "string" }, "address_line_2": { "type": "string" }, "address_city": { "type": "string" }, "address_state": { "type": "string" }, "address_postal_code": { "type": "string" }, "address_country_code": { "description": "2-character ISO 3166-1 alpha-2 country code, e.g. \"US\".", "type": "string" } } }, "TransactionBody": { "properties": { "transaction_id": { "description": "Unique external identifier for the transaction. Required if using counterparty MLA." }, "transaction_date": { "description": "ISO 8601 date. Used as the transaction's date or date to look back from when evaluating an account.", "type": "string" }, "amount": { "description": "Amount in cents", "type": "integer" }, "currency": { "description": "3-character currency code (e.g. \"USD\")", "type": "string" }, "source": { "type": "object", "$ref": "#/components/schemas/SourceAccount" }, "destination": { "type": "object", "$ref": "#/components/schemas/DestinationAccount" }, "account_snapshot": { "description": "Snapshot of the source account of the transaction. Note that this is not a separate call, it is part of either an /accounts call or an /evaluations call", "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AccountSnapshot" } ] }, "process_method": { "description": "Platform or process method of the transaction. Allowed values are (`\"Card\"`. `\"Internal\"`, `\"Check\"`, `\"P2P\"`, `\"ACH\"`, `\"Cash\"`, `\"Wire\"`, `\"Digital Wallet\"`, `null`)", "type": "string", "nullable": true, "enum": [ "Card", "Internal", "Check", "P2P", "ACH", "Cash", "Wire", "RTP", "Digital Wallet" ] }, "category": { "description": "Splits process_method into more granular values. Allowed values are (`\"Adjustment\"`, `\"ATM Rebate\"`, `\"Bill Pay\"`, `\"Chargeback\"`, `\"Deposit\"`, `\"Direct Deposit Bonus\"`, `\"Interest\"`, `\"Overdraft Fee\"`, `\"Payment\"`, `\"Promo\"`, `\"Purchase\"`, `\"Purchase Return\"`, `\"Return\"`, `\"Service Charge\"`, `\"Withdrawal\"`, `null`)", "type": "string", "nullable": true, "enum": [ "Adjustment", "ATM Rebate", "Bill Pay", "Chargeback", "Deposit", "Direct Deposit Bonus", "Interest", "Overdraft Fee", "Payment", "Promo", "Purchase", "Purchase Return", "Return", "Service Charge", "Withdrawal" ] }, "interaction_point": { "description": "Where the transaction took place. Allow values are (`\"Android\"`, `\"ATM\"`, `\"Card Swipe Terminal\"`, `\"iOS\"`, `\"Mobile\"`, `\"Online Form\"`, `\"Point of Sale\"`, `\"QR\"`, `\"Teller\"`, `\"3rd Party App\"`, `null`)", "type": "string", "nullable": true, "enum": [ "Android", "ATM", "Card Swipe Terminal", "iOS", "Mobile", "Online Form", "Point of Sale", "QR", "Teller", "3rd Party App" ] }, "type_code": { "description": "The raw type code of the transaction. There should be a 1:1 mapping from type_code to type_description provided to Alloy.", "type": "string", "nullable": true }, "type_description": { "description": "Description of the type code. There should be a 1:1 mapping from type_code to type_description provided to Alloy. Currently not used in decisioning.", "type": "string", "nullable": true }, "is_approved": { "description": "If the transaction was approved by the customer", "type": "boolean", "nullable": true }, "is_reversal": { "description": "If the transaction is a refund", "type": "boolean", "nullable": true }, "is_triggered_by_user": { "description": "Whether the transaction is initiated by the source entity. Mainly used to distinguish between ACH push and pull", "type": "boolean", "nullable": true }, "is_international_override": { "description": "True if the transaction is international", "type": "boolean", "nullable": true }, "return_code": { "description": "This represents the Alphanumeric ACH return Code. (e.g. R01)", "type": "string", "nullable": true }, "return_code_reason": { "description": "Allowed values are (`\"Unauthorized\"`, `null`). Currently not used in decisioning.", "type": "string", "nullable": true, "enum": [ "Unauthorized" ] }, "entry_mode": { "description": "POS entry modes on card transactions", "type": "number", "nullable": true }, "response_code": { "description": "Response codes returned on card transactions", "type": "number", "nullable": true }, "status": { "description": "Allowed values are (`\"Acknowledged\"`, `\"Accepted\"`, `\"Rejected\"`, `\"Paused\"`, `\"Pending\"`, `\"Completed\"`, `\"Declined\"`, `\"Cancelled\"`, `null`)", "type": "string", "nullable": true, "enum": [ "Acknowledged", "Accepted", "Rejected", "Paused", "Pending", "Completed", "Declined", "Cancelled" ] }, "status_detail": { "description": "Additional description on transaction status. Currently not used in decisioning.", "type": "string", "nullable": true }, "iso_message": { "description": "ISO standard value returned on card transactions", "type": "number", "nullable": true }, "settled_at": { "description": "ISO 8601 date. Currently not used in decisioning.", "type": "string", "nullable": true }, "latest_transaction_date": { "description": "ISO 8601 date. Currently not used in decisioning.", "type": "string", "nullable": true }, "description": { "description": "A description of the transaction. Currently not used in decisioning.", "type": "string", "nullable": true }, "approval_code": { "description": "The raw approval code provided by the customer. Currently not used in decisioning.", "type": "string", "nullable": true }, "transaction_meta": { "description": "Object containing extra raw data not stored in other columns. Currently not used in decisioning.", "type": "object", "nullable": true } } }, "TransactionEvaluationRequestBody": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/TransactionBody" } ], "required": [ "transaction_id", "transaction_date", "amount", "source", "destination", "currency" ] }, "TransactionEvaluationBody": { "allOf": [ { "$ref": "#/components/schemas/TransactionEvaluationRequestBody" } ] } }, "parameters": { "AlloySandboxPersonaToken": { "in": "header", "name": "alloy-sandbox-persona-token", "schema": { "type": "string", "description": "Instead of using the configured business and person identifier (for example, the last name DenyFraud), this header references the corresponding sandbox profile/persona using its sandbox profile token, found on the Sandbox Profile page.\n", "example": "E-tSXbp2UBPwiA5a9wsBwN" } } } }, "x-readme": { "explorer-enabled": false } } ```