Check feature eligibility

See what a customer still needs before you activate cards for them. An eligible value of false is normal before activation.

Check what a customer still needs before you activate the card feature (virtual_cards). The eligibility check shows which requirements the customer meets and which ones remain unmet.

A money example. Ada will spend about 300 USD a month on her card. The check shows her KYC is completed and lists annual_remuneration and estimated_monthly_limit as pending. You send 24000 and 300 at activation.

Check eligibility for a feature

Use the Check feature eligibility endpoint to check whether a customer can activate a feature. Send customer_id and feature_id in the request body. The endpoint only reads data, but it is a POST, so it needs an Idempotency-Key. Send a new key for every check, or you get the stored result of the earlier check:

curl --request POST \
     --url https://api.gravv.xyz/v1/risk/features/eligibility \
     --header 'Api-Key: <API_KEY>' \
     --header 'Idempotency-Key: 6cdc7e56-a82b-4877-a00a-37a0c86ad823' \
     --header 'Content-Type: application/json' \
     --data '
{
  "customer_id": "5b0f6c1e-2a8f-4c39-9d0e-0c7e3b9a1f42",
  "feature_id": "virtual_cards"
}
'

Understanding the response

For virtual_cards, eligible stays false until you activate. You send the provider_data fields in the activation request, and Gravv does not store them before activation. Treat each pending provider_data item as a field to send to Activate feature. Once kyc_status is fulfilled, the customer is ready for activation.

The response shows eligible: false and lists the unmet requirements under requirements_pending:

{
  "data": {
    "customer_id": "5b0f6c1e-2a8f-4c39-9d0e-0c7e3b9a1f42",
    "eligible": false,
    "feature_id": "virtual_cards",
    "requirements_fulfilled": [
      {
        "type": "kyc_status",
        "value": "completed",
        "fulfilled_at": "2025-12-16T10:52:29Z"
      }
    ],
    "requirements_pending": [
      {
        "type": "provider_data",
        "required": "annual_remuneration",
        "action": {
          "type": "provider_data",
          "data_key": "annual_remuneration"
        }
      },
      {
        "type": "provider_data",
        "required": "estimated_monthly_limit",
        "action": {
          "type": "provider_data",
          "data_key": "estimated_monthly_limit"
        }
      },
      {
        "type": "provider_data",
        "required": "ip_address",
        "action": {
          "type": "provider_data",
          "data_key": "ip_address"
        }
      }
    ]
  },
  "error": null
}

In this example, the customer has completed KYC, and you send the provider data at activation. Gravv fills in the ip_address item at activation from the address your request comes from. Pending items carry type, required and action. There is no provider field.

If kyc_status is in requirements_pending, verify the customer first (Verify a cardholder).

Every error from this endpoint is HTTP 400 Failed to check feature eligibility, whether the feature_id is unknown or the customer has no KYC record. The exception is an invalid or unknown customer_id, which returns its own message.