# Evaluate a Route

`POST /v2/routes/{id}/evaluation`

Core API v2, Routes.

Shows where a Route would send a payment, without creating one. Send the payment's facts, and either a published `version`, a `tree` you have not published, or neither to use the active version. The answer lists the gateway profiles the payment would be sent to, in order, and every node the Route reached on the way. Nothing is charged or stored. Gateway profiles are taken as they are now, so an inactive one is skipped. A `roundRobin` pool starts where the next payment would start it. A `weighted` pool draws a new random order on every request, as each payment does.

**Authentication:** Send `Authorization: Bearer <token>`. To authenticate, generate a Secret API Key from your ODUS Dashboard and include it in the `Authorization` header as follows: `Authorization: Bearer <YOUR_SECRET_API_KEY>`

## Parameters

### Path parameters

- `id` (string, required)

## Request body

Content type `application/json`, required.

Type: object (EvaluateRouteRequestDTO).

- `version` (string): The ID of a published version of this route to evaluate. Leave out both `version` and `tree` to evaluate the route's active version. Minimum length 1. Example: `rtv_2mXGTxXIkqv4uSdbm8DJCzvHUIu`.
- `tree` (object or object or object or object): A decision tree to evaluate instead of a published version, such as one you have not published yet. It takes the same shape as `tree` in Publish a Route version.
  - When the value is variant 1:
    - `type` (string, required): One of `condition`.
    - `branches` (array of object, required): Tested in order. The payment follows the first branch whose condition matches. A decline inside that branch does not move on to a later branch. Minimum items 1. Maximum items 20.
      - `when` (object or object or object or object, required): A test on the payment: a single comparison, or `all`, `any` or `not` over other conditions. A fact the payment does not have makes the comparison unknown, never false, and an unknown condition does not match.
        - When the value is variant 1:
          - `all` (array of (object or object or object or object), required): Minimum items 1.
            - Same fields as `RouteConditionDTO`, described above.
        - When the value is variant 2:
          - `any` (array of (object or object or object or object), required): Minimum items 1.
            - Same fields as `RouteConditionDTO`, described above.
        - When the value is variant 3:
          - `not` (object or object or object or object, required): A test on the payment: a single comparison, or `all`, `any` or `not` over other conditions. A fact the payment does not have makes the comparison unknown, never false, and an unknown condition does not match.
            - Same fields as `RouteConditionDTO`, described above.
        - When the value is variant 4:
          - `field` (string, required): The payment fact to test: `card.brand`, `card.bin`, `card.issuerName`, `card.issuerCountry`, `card.fundingType`, `amount`, `currency`, `initiator`, `statementDescriptor`, `statementDescriptorSuffix`, or `metadata.<key>`. Minimum length 1. Example: `card.issuerCountry`.
          - `op` (string, required): How the fact is compared with `value`. Each field supports its own operators. One of `eq`, `ne`, `in`, `nin`, `gt`, `gte`, `lt`, `lte`, `contains`, `startsWith`, `exists`.
          - `value` (string or integer or array of string): What the fact is compared with: a list for `in` and `nin`; a prefix or a list of prefixes for `startsWith`; a number in minor units for `amount`; omitted for `exists`. Example: `US`.
      - `then` (object or object or object or object, required): One step of a route: a `condition`, a `split`, a `pool` or a `gateway`.
        - Same fields as `RouteNodeDTO`, described above.
    - `else` (object or object or object or object): Followed when no branch matches. Without it, the route ends there.
      - Same fields as `RouteNodeDTO`, described above.
  - When the value is variant 2:
    - `type` (string, required): One of `split`.
    - `outputs` (array of object, required): Each payment follows exactly one output, chosen in proportion to `percent`. The same payment follows the same output each time it reaches this split. A decline inside that output does not move on to another output. Minimum items 2. Maximum items 20.
      - `percent` (integer, required): The share of payments that follow this output, as a whole percentage. The percentages of one split add up to 100. Minimum 1. Maximum 99. Example: `20`.
      - `then` (object or object or object or object, required): One step of a route: a `condition`, a `split`, a `pool` or a `gateway`.
        - Same fields as `RouteNodeDTO`, described above.
  - When the value is variant 3:
    - `type` (string, required): One of `pool`.
    - `strategy` (string, required): The order the children are tried in. `ordered` keeps the written order; `roundRobin` starts at a position that moves on from one payment to the next; `weighted` picks the order at random, in proportion to `weights`. One of `ordered`, `roundRobin`, `weighted`.
    - `children` (array of (object or object or object or object), required): Tried in turn. When a child declines, the pool fails over to the next one; a child that is not attempted, such as an inactive gateway, is passed over. Minimum items 1. Maximum items 20.
      - Same fields as `RouteNodeDTO`, described above.
    - `weights` (array of integer): One weight per child, for a `weighted` pool only. Each item: Minimum 1. Maximum 100.
    - `maxAttempts` (integer): The most gateway attempts this pool may make, including those of its children. Minimum 1. Maximum 11.
  - When the value is variant 4:
    - `type` (string, required): One of `gateway`.
    - `gatewayProfileId` (string, required): The gateway profile to attempt. It must be active and support card payments when the version is published. Minimum length 1. Example: `gwp_2mXGTxXIkqv4uSdbm8DJCzvHUIu`.
- `facts` (object, required): The payment to evaluate the route's conditions against.
  - `amount` (integer, required): The amount of the payment, in minor units. Minimum 0. Maximum 9007199254740991. Example: `1000`.
  - `currency` (string, required): The currency of the payment. One of `usd`, `eur`, `gbp`, `cad`, `aud`, `pln`, `czk`, `sek`, `dkk`. Example: `usd`.
  - `initiator` (string, required): Who initiates the payment. One of `customer`, `merchant`. Example: `customer`.
  - `card` (object): What is known about the card. A condition on a card field you leave out cannot be decided, so it does not match.
    - `brand` (string): The brand of the card. One of `visa`, `mastercard`, `amex`, `discover`. Example: `visa`.
    - `bin` (string): The first 6 to 8 digits of the card number. Never send the full card number. Pattern `^\d{6,8}$`. Example: `41472000`.
    - `issuerName` (string): The name of the bank that issued the card. Minimum length 1. Maximum length 255. Example: `Capital One`.
    - `issuerCountry` (string): The country of the bank that issued the card, as an ISO 3166-1 alpha-2 code. Pattern `^[A-Za-z]{2}$`. Example: `US`.
    - `fundingType` (string): How the card is funded, such as `credit`, `debit`, `prepaid` or `charge` Minimum length 1. Maximum length 50. Example: `credit`.
  - `metadata` (map of string to string, nullable): The payment's metadata, for conditions on `metadata.<key>`
  - `statementDescriptor` (string): The payment's statement descriptor. A condition on `statementDescriptor` cannot be decided without it, so it does not match. Minimum length 1. Maximum length 22. Example: `Some product`.
  - `statementDescriptorSuffix` (string): The payment's statement descriptor suffix. A condition on `statementDescriptorSuffix` cannot be decided without it, so it does not match. Minimum length 1. Maximum length 22. Example: `PRO PLAN`.

## Responses

### `200`

OK

Type: object (RouteEvaluationDTO).

- `route` (string, required): The ID of the route that was evaluated. Example: `rte_2mXGTxXIkqv4uSdbm8DJCzvHUIu`.
- `routeVersion` (string, required, nullable): The ID of the version that was evaluated, or `null` when the request sent its own `tree` Example: `rtv_2mXGTxXIkqv4uSdbm8DJCzvHUIu`.
- `attempts` (array of object, required): The gateway profiles the payment would be sent to, in order. Each one is attempted only if every attempt before it declined. Empty when the route would attempt none.
  - `attempt` (integer, required): Where the attempt comes in the order, counted from 1. Minimum -9007199254740991. Maximum 9007199254740991. Example: `1`.
  - `gatewayProfile` (string, required): The ID of the gateway profile that would be attempted. Example: `gwp_2mXGTxXIkqv4uSdbm8DJCzvHUIu`.
  - `route` (string, required): The ID of the route the gateway node belongs to. Example: `rte_2mXGTxXIkqv4uSdbm8DJCzvHUIu`.
  - `path` (string, required): Where the gateway node sits in the route's decision tree. Example: `$.branches[0].then.children[1]`.
- `steps` (array of object, required): Every node the route reached, in the order it reached them, with what it decided there.
  - `route` (string, required): The ID of the route the node belongs to. Example: `rte_2mXGTxXIkqv4uSdbm8DJCzvHUIu`.
  - `path` (string, required): Where the node sits in the route's decision tree. Example: `$.branches[0].then.children[1]`.
  - `result` (string, required): What the route decided at the node. `matched`: a condition took the branch in `branch`. `no_match`: the branch in `branch` did not match. `unknown_fact`: the branch could not be decided because the facts lacked the fields in `unknownFields`, so it did not match. `skipped`: the node was passed over for the `reason` given. `attempted`: the payment would be sent to `gatewayProfile` as attempt number `attempt`. An evaluation never answers `withheld`. One of `matched`, `no_match`, `unknown_fact`, `skipped`, `attempted`, `withheld`. Example: `matched`.
  - `branch` (string, required, nullable): For a condition, the index of the branch, counted from 0, or `else`. `null` for other nodes. Example: `0`.
  - `reason` (string, required, nullable): Why a node was `skipped`; `null` otherwise. The reasons are those of a route execution step, and new ones may be added: treat a reason you do not recognise as an explanation only. Example: `gateway_inactive`.
  - `gatewayProfile` (string, required, nullable): The ID of the gateway profile the node names, or `null` for a node that names none. Example: `gwp_2mXGTxXIkqv4uSdbm8DJCzvHUIu`.
  - `attempt` (integer, required, nullable): For an `attempted` step, where the attempt comes in the order, counted from 1; `null` otherwise. Minimum -9007199254740991. Maximum 9007199254740991. Example: `1`.
  - `unknownFields` (array of string, required, nullable): For an `unknown_fact` step, the fields the condition needed that the facts did not have; `null` otherwise.
  - `unsupportedTerms` (array of string, required, nullable): For an `unknown_fact` step, the parts of the condition that could not be evaluated, as `<field> <operator>`; `null` when there were none.
  - `targetRoute` (string, required, nullable): For a skipped `route` node, the ID of the route it names; `null` otherwise. Example: `rte_2mXGTxXIkqv4uSdbm8DJCzvHUIu`.

### `202`

The merchant is entitled but its environment is not provisioned yet. Provisioning has been kicked off (exactly once) and is in progress; retry the request — it succeeds once the environment is ready. Returned only for identity-token (dashboard) requests bound to a merchant, not for secret-key API calls; any such endpoint can return it while provisioning is underway.

Type: object (ProvisioningInProgress).

- `status` (string, required): Signals the merchant environment is still being provisioned. One of `provisioning`.
- `merchantAccountId` (string, required): The merchant account whose environment is being provisioned. Example: `dAI3aa87ROOeupeBCjNSKCOBOisBCYjB`.

### Errors

- `400`: The request was rejected. `type` is `invalid_request_error` when the request itself is at fault — `errors` then lists every problem found, with field-attributable entries prefixed by the field’s path; or `invalid_state_error` when the request was well-formed but the resource is not in a state that allows it.
- `401`: No API key was supplied, or the key is not valid. `type` is `authentication_error`.
- `403`: The API key is valid but lacks the permission this operation requires. `type` is `permission_error`.
- `404`: No resource exists with the requested identifier. `type` is `not_found_error`.
- `429`: Too many requests. A limit applies per operation; requests to other operations are unaffected. `type` is `rate_limit_error`. Use the `Retry-After-global` header to know when to retry.
- `500`: The request could not be completed because of an unexpected error. `type` is `api_error`.
- `503`: The request could not be served right now: the API is temporarily at capacity, or a dependency needed to authorize the request is unavailable — the auth service that verifies credentials, or the entitlement lookup behind it. `type` is `api_error`. It is raised before the operation runs, so the request had no effect, and unlike a plain 500 the condition is transient: retry with backoff.
- `504`: The request exceeded the processing time limit and was abandoned. `type` is `api_error` and `code` is `timeout` — unlike a plain 500 the request may still have taken effect, so retry with the same idempotency key rather than blindly.

Every error response has the same body: see [Errors](https://docs.odus.com/docs/guides/api-features/errors.md).

---

Generated from the Core API v2 OpenAPI document, https://api.odus.com/openapi.v2.json. Interactive page: https://docs.odus.com/docs/api/core/v2/route-evaluation-controller-evaluate