Activate feature

Once you've verified that a customer is eligible for a feature, you can activate it for their account. Some features require additional provider data during activation.

Activate a feature

Use the Activate a feature endpoint to enable a feature for a customer. The request requires the customer_id, feature_id, and optionally provider_data:

curl --request POST \
     --url https://api.gravv.xyz/v1/risk/features/activate \
     --header 'Api-Key: <API_KEY>' \
     --header 'Idempotency-Key: 979879887678789_attempt_1' \
     --header 'content-type: application/json' \
     --data '
{
  "customer_id": "302dabcb-d4fd-4a00-a80b-afad70982614",
  "feature_id": "virtual_cards",
  "provider_data": {
    "annual_remuneration": 120000,
    "estimated_monthly_limit": 5000,
    "ip_address": "192.168.1.100",
    "account_id": "5d9e677f-f071-4881-a861-7cdcebacd9d5"
  }
}
'

You will receive a confirmation response. For virtual_cards, activation also creates the customer's card application, so the response carries the new application_id under data.data:

{
  "data": {
    "activated_at": "2026-01-09T10:29:16.000Z",
    "customer_id": "302dabcb-d4fd-4a00-a80b-afad70982614",
    "feature_id": "virtual_cards",
    "status": "active",
    "data": {
      "application_id": "a14ec356-f33d-4384-ba68-4d9bfa19765b"
    }
  },
  "error": null
}

📘 Cards start here

Activating virtual_cards is how you create a card application. There's no separate "submit application" call to make in production. Save the application_id, track it until it's approved, then create the card. See Create a card application.

Provider data requirements

The provider_data object carries feature-specific information that activation needs. The fields depend on the feature. Activating virtual_cards requires:

Field	Type	Required	Description
annual_remuneration	number	yes	Customer's expected annual inflow in USD
estimated_monthly_limit	number	yes	Expected monthly card spend in USD. Must be lower than annual_remuneration
ip_address	string	yes	IP address the request comes from
account_id	string	no	The card account that backs the card. Gravv derives it from your tenant's card account if you leave it out

Use Check feature eligibility first to see which of these the customer still needs to supply.

Liveness check requirement

When activating card features, the system checks whether the customer has completed their liveness verification. If they haven't, activation can't finish: the status comes back as pending_liveness and the response includes a websdk_url instead of an application_id:

{
  "data": {
    "customer_id": "302dabcb-d4fd-4a00-a80b-afad70982614",
    "feature_id": "virtual_cards",
    "status": "pending_liveness",
    "websdk_url": "https://verify.gravv.xyz/liveness/abc123xyz"
  },
  "error": null
}

Redirect the customer to the websdk_url to finish their liveness verification, then call Activate feature again. Activation is idempotent, so the retry returns the existing application instead of creating a second one.