# Access request for elastic tokens

API to request products, features or other items that will be charged for using elastic tokens.

Endpoint: POST /elastic/api/v1.1/instances/{instanceId}/access-request
Version: v1.1
Security: AdministrationAccess, ClientAccess

## Security:

  - `AdministrationAccess` (unknown)
    http bearer JWT

  - `ClientAccess` (unknown)
    http bearer JWT

## Path parameters:

  - `instanceId` (string, required)
    The UUID of the Dynamic Monetization instance.

## Header parameters:

  - `correlationId` (string)
    An optional identifier for the request. If provided, it is recommended to use a UUID format to minimise the risk of reusing the same correlationId.

This field can be used to support safe retries, typically when the request has timed out. The safe retry configuration option must be enabled first,
refer to the Configuration section for more information on how to enable this.

If no correlationId is supplied, Dynamic Monetization will generate one automatically.

## Request body:

  - `application/json` (unknown)
    The information required in the request payload.

## Request fields (application/json):

  - `requester` (object, required)
    Requester details

  - `requester.type` (string)
    Type of the requester.

  - `requester.value` (string)
    Unique identifier for the requester.

  - `requestedItems` (array, required)
    A list of requested items.

  - `requestedItems.item` (string)
    The requested item.

  - `requestedItems.version` (string)
    The version of the item requested. This field may only be omitted or left blank if the intention is to access an item in a rate table with an empty or unspecified version.

  - `requestedItems.count` (number)
    Number of instances of the requested item required. The value can be fractional.

  - `requestedItems.variables` (object)
    A collection of named input values used for evaluating formula-based token consumption in an access request. Each key represents a variable identifier referenced in the configured rate table formula, and the corresponding value is the numeric input used to evaluate the formula.
The `variables` field is mutually exclusive with the `count` field. Requests must include either `count` (for fixed-rate) or `variables` (for formula-based), but not both.
- At least one variable must be provided.
- Variable names must match those defined in the formula.
- Variable values must be numeric.

  - `requestedItems.metaData` (object)
    (Optional) For sending custom data with the request, which will be sent to the data warehouse with the usage information to assist with analyzing access activity. The meta data content must be a valid JSON object.

## Response 200:

  - `200` (unknown)
    OK The request succeeded in its entirety

## Response 200 fields (application/json):

  - `requestedItems` (array)
    List of requested items.

  - `requestedItems.count` (number)
    Number of instances of the requested item granted. The value can be fractional.

  - `requestedItems.variables` (object)
    The variables associated with the requested item that were used to calculate tokens required based on formula.
Response will have either `count` or `variables` depending on what was sent in the request.

  - `requestedItems.item` (string)
    The name of a requested item.

  - `requestedItems.version` (string)
    The version of a requested item.

  - `requestedItems.totalTokensCharged` (number)
    Total number of tokens charged across all line items. The value can be fractional.

  - `requestedItems.lineItems` (array)
    List of line items charged to fulfill this request.

  - `requestedItems.lineItems.rate` (number)
    Rate applied. The value can be fractional.

  - `requestedItems.lineItems.formula` (string)
    The formula used to calculate the charge for this line item. This field is only applicable if the line item was charged based on a formula. If the charge was based on a fixed rate, this field will be absent.

  - `requestedItems.lineItems.activationId` (string)
    Activation ID of line item charged to fulfill the request.

  - `requestedItems.lineItems.tokensCharged` (number)
    Number of tokens charged. The value can be fractional.

  - `requestedItems.lineItems.actionId` (string)
    Unique identifier of the action and allocation used if the access request was fulfilled from an allocation within the line item.

  - `requestedItems.lineItems.consumptionLimitId` (string)
    Unique identifier of the consumption limit used when the access request was fulfilled from a consumption limit on the line item.
    Example: autoTracked

  - `requestedItems.status` (object)
    The response status to the request for the specific item.

  - `requestedItems.status.code` (string)
    Possible values
* 1001 (Successfully checked out)
* 1002 (No Status)
* 2001 (Item not found in any effective rate table)
* 3001 (No valid active line items)
* 3006 (Insufficient count available)
* 3007 (Requester consumption limit exceeded)
* 4001 (Failed due to internal server error) There was an internal error processing the request. If you need to contact support, please include the correlationId provided in the response.

  - `requestedItems.status.description` (string)
    A user-readable message explaining the status code.
    Example: Successfully checked out.

  - `instanceConsumptionLimitId` (string)
    Unique identifier of the consumption limit used when the access request was fulfilled from a consumption limit on the instance.
    Example: autoTracked

  - `notifications` (object)
    Notification details for this access request when a consumption limit is
configured with `notificationId` set to `accessResponseBody` and consumption
crosses a configured threshold percentage of the consumption limit.
If multiple thresholds are crossed while processing the request, the
response includes only the highest threshold crossed.
The same threshold can appear again in a later response if consumption drops
below that threshold and subsequently crosses it again.

  - `notifications.instanceConsumptionLimit` (object)
    Notification details for the instance consumption limit.

  - `notifications.instanceConsumptionLimit.id` (string)
    Unique identifier of the instance consumption limit that triggered the notification.
    Example: autoTracked

  - `notifications.instanceConsumptionLimit.message` (string)
    Notification message describing the configured consumption threshold that was crossed and the current consumption percentage of the consumption limit after the access request was processed.
    Example: Requester usage has exceeded the 25% consumption limit threshold. Usage is currently at 25.5%.

  - `requester` (object)
    Requester details

  - `requester.type` (string)
    Type of the requester.

  - `requester.value` (string)
    Unique identifier for the requester.

  - `correlationId` (string)
    An ID which allows correlation of the request with usage information obtained from the data warehouse.

## Response 400:

  - `400` (unknown)
    Bad Request. Check the request for any errors in the input.

## Response 401:

  - `401` (unknown)
    Unauthorized. Check authentication details.

## Response 500:

  - `500` (unknown)
    Internal Server Error. There was an internal error processing the request. If you need to contact support, please include the reference number provided in the response.

## Response 503:

  - `503` (unknown)
    API is temporarily unavailable. Try again later.