Retrieve an Item

v1.0.0

Returns information about the status of an Item.

Input

{
  "type": "object",
  "description": "ItemGetRequest defines the request schema for `/item/get`",
  "required": [
    "access_token"
  ],
  "properties": {
    "access_token": {
      "type": "string",
      "description": "The access token associated with the Item data is being requested for."
    },
    "client_id": {
      "type": "string",
      "description": "Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body."
    },
    "secret": {
      "type": "string",
      "description": "Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body."
    }
  }
}

Output

{
  "type": "object",
  "description": "ItemGetResponse defines the response schema for `/item/get` and `/item/webhook/update`",
  "required": [
    "item",
    "request_id"
  ],
  "properties": {
    "item": {
      "type": "object",
      "description": "Metadata about the Item.",
      "required": [
        "available_products",
        "billed_products",
        "consent_expiration_time",
        "error",
        "item_id",
        "update_type",
        "webhook"
      ],
      "properties": {
        "available_products": {
          "type": "array",
          "description": "A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with `billed_products`.",
          "items": {
            "type": "string",
            "description": "A list of products that an institution can support. All Items must be initialized with at least one product. The Balance product is always available and does not need to be specified during initialization.",
            "enum": [
              "assets",
              "auth",
              "balance",
              "identity",
              "investments",
              "liabilities",
              "payment_initiation",
              "identity_verification",
              "transactions",
              "credit_details",
              "income",
              "income_verification",
              "deposit_switch",
              "standing_orders",
              "transfer",
              "employment",
              "recurring_transactions"
            ]
          }
        },
        "billed_products": {
          "type": "array",
          "description": "A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with `available_products`. Note - `billed_products` is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as `balance`, will not appear here.\n",
          "items": {
            "type": "string",
            "description": "A list of products that an institution can support. All Items must be initialized with at least one product. The Balance product is always available and does not need to be specified during initialization.",
            "enum": [
              "assets",
              "auth",
              "balance",
              "identity",
              "investments",
              "liabilities",
              "payment_initiation",
              "identity_verification",
              "transactions",
              "credit_details",
              "income",
              "income_verification",
              "deposit_switch",
              "standing_orders",
              "transfer",
              "employment",
              "recurring_transactions"
            ]
          }
        },
        "consent_expiration_time": {
          "type": "string",
          "format": "date-time",
          "description": "The RFC 3339 timestamp after which the consent provided by the end user will expire. Upon consent expiration, the item will enter the `ITEM_LOGIN_REQUIRED` error state. To circumvent the `ITEM_LOGIN_REQUIRED` error and maintain continuous consent, the end user can reauthenticate via Link’s update mode in advance of the consent expiration time.\n\nNote - This is only relevant for certain OAuth-based institutions. For all other institutions, this field will be null.\n"
        },
        "consented_products": {
          "type": "array",
          "description": "Beta: A list of products that have gone through consent collection for the Item. Only present for those enabled in the beta.\n",
          "items": {
            "type": "string",
            "description": "A list of products that an institution can support. All Items must be initialized with at least one product. The Balance product is always available and does not need to be specified during initialization.",
            "enum": [
              "assets",
              "auth",
              "balance",
              "identity",
              "investments",
              "liabilities",
              "payment_initiation",
              "identity_verification",
              "transactions",
              "credit_details",
              "income",
              "income_verification",
              "deposit_switch",
              "standing_orders",
              "transfer",
              "employment",
              "recurring_transactions"
            ]
          }
        },
        "error": {
          "type": "object",
          "description": "We use standard HTTP response codes for success and failure notifications, and our errors are further classified by `error_type`. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead.",
          "required": [
            "display_message",
            "error_code",
            "error_message",
            "error_type"
          ],
          "properties": {
            "causes": {
              "type": "array",
              "description": "In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.\n\n`causes` will only be provided for the `error_type` `ASSET_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object.",
              "items": {
                "type": "object"
              }
            },
            "display_message": {
              "type": "string",
              "description": "A user-friendly representation of the error code. `null` if the error is not related to user action.\n\nThis may change over time and is not safe for programmatic use."
            },
            "documentation_url": {
              "type": "string",
              "description": "The URL of a Plaid documentation page with more information about the error"
            },
            "error_code": {
              "type": "string",
              "description": "The particular error code. Safe for programmatic use."
            },
            "error_message": {
              "type": "string",
              "description": "A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use."
            },
            "error_type": {
              "type": "string",
              "description": "A broad categorization of the error. Safe for programmatic use.",
              "enum": [
                "INVALID_REQUEST",
                "INVALID_RESULT",
                "INVALID_INPUT",
                "INSTITUTION_ERROR",
                "RATE_LIMIT_EXCEEDED",
                "API_ERROR",
                "ITEM_ERROR",
                "ASSET_REPORT_ERROR",
                "RECAPTCHA_ERROR",
                "OAUTH_ERROR",
                "PAYMENT_ERROR",
                "BANK_TRANSFER_ERROR",
                "INCOME_VERIFICATION_ERROR",
                "MICRODEPOSITS_ERROR"
              ]
            },
            "request_id": {
              "type": "string",
              "description": "A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks."
            },
            "status": {
              "type": "number",
              "description": "The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook."
            },
            "suggested_action": {
              "type": "string",
              "description": "Suggested steps for resolving the error"
            }
          }
        },
        "institution_id": {
          "type": "string",
          "description": "The Plaid Institution ID associated with the Item. Field is `null` for Items created via Same Day Micro-deposits."
        },
        "item_id": {
          "type": "string",
          "description": "The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive."
        },
        "products": {
          "type": "array",
          "description": "A list of authorized products for the Item.\n",
          "items": {
            "type": "string",
            "description": "A list of products that an institution can support. All Items must be initialized with at least one product. The Balance product is always available and does not need to be specified during initialization.",
            "enum": [
              "assets",
              "auth",
              "balance",
              "identity",
              "investments",
              "liabilities",
              "payment_initiation",
              "identity_verification",
              "transactions",
              "credit_details",
              "income",
              "income_verification",
              "deposit_switch",
              "standing_orders",
              "transfer",
              "employment",
              "recurring_transactions"
            ]
          }
        },
        "update_type": {
          "type": "string",
          "description": "Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication.\n\n`background` - Item can be updated in the background\n\n`user_present_required` - Item requires user interaction to be updated",
          "enum": [
            "background",
            "user_present_required"
          ]
        },
        "webhook": {
          "type": "string",
          "description": "The URL registered to receive webhooks for the Item."
        }
      }
    },
    "request_id": {
      "type": "string",
      "description": "A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive."
    },
    "status": {
      "description": "Information about the last successful and failed transactions update for the Item.",
      "type": "object"
    }
  }
}