Enrollments

Enrollments link a Basis Theory card token to an agent through a network provider (Visa or Mastercard). During enrollment, the card brand is auto-detected and the card is registered with the corresponding network. The consumer must verify ownership before the enrollment can be used.

Authentication

All requests require a BT-API-KEY header with your Basis Theory API key.

All errors follow the standard error response format.

List Enrollments

Returns a paginated list of enrollments for your tenant.

GET

https://api.basistheory.com/agentic/enrollments

Permissions

enrollment:get

Request

curl 'https://api.basistheory.com/agentic/enrollments?limit=25' \
  -H 'BT-API-KEY: <BT_API_KEY>'

Request Parameters

Attribute	Required	Type	Description
limit	No	integer	Number of results to return (default: 25, max: 100)
cursor	No	string	Opaque pagination cursor from a previous response

Response

Returns a paginated list of enrollment objects.

{
  "data": [
    {
      "id": "enr_wNe75VKdzvojI9iD5fJxr",
      "provider": "visa",
      "status": "active",
      "card": {
        "brand": "visa",
        "bin": "424032",
        "last4": "0359",
        "expiration_month": 11,
        "expiration_year": 2029,
        "display": {
          "art_url": "https://assets.vims.visa.com/vims/cardart/abc123",
          "background_color": "1A1F71",
          "foreground_color": "FFFFFF",
          "description": "Visa Signature",
          "issuer_name": "Chase"
        }
      },
      "created_at": "2026-01-15T10:31:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImVucl93TmU3NVZLZHp2b2pJOWlENWZKeHIifQ",
    "has_more": false
  }
}

Create Enrollment

Enrolls a card with a network provider. The card brand is auto-detected from the Basis Theory token data.

POST

https://api.basistheory.com/agentic/enrollments

Permissions

enrollment:create

Visa is fully supported. Mastercard support via Mastercard Agent Pay is available through a limited waitlist — contact support@basistheory.com to request access.

Request

curl -X POST https://api.basistheory.com/agentic/enrollments \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "token_id": "<TOKEN_ID>",
    "consumer": {
      "email": "consumer@example.com",
      "id": "user-123",
      "country_code": "US",
      "language_code": "en"
    },
    "agent_ids": ["<AGENT_ID_1>", "<AGENT_ID_2>"]
  }'

Request Parameters

Attribute	Required	Type	Description
token_id	Yes	string	The Basis Theory card token ID
consumer	Yes	object	The consumer object
agent_id	No	string	Associate the enrollment with a single agent. Mutually exclusive with agent_ids
agent_ids	No	array	Associate the enrollment with multiple agents (max 50). Mutually exclusive with agent_id. Duplicates are silently deduplicated

Consumer Object

Attribute	Required	Type	Description
email	Yes	string	The consumer's email address
id	No	string	An identifier for the consumer in your system
country_code	No	string	ISO 3166-1 alpha-2 country code (default: US)
language_code	No	string	Language code (default: en)

Response

Returns an enrollment object if successful. The enrollment will have pending_verification status until the consumer completes verification.

{
  "id": "enr_wNe75VKdzvojI9iD5fJxr",
  "provider": "visa",
  "status": "pending_verification",
  "card": {
    "brand": "visa",
    "bin": "424032",
    "last4": "0359",
    "expiration_month": 11,
    "expiration_year": 2029,
    "display": {
      "art_url": "https://assets.vims.visa.com/vims/cardart/abc123",
      "background_color": "1A1F71",
      "foreground_color": "FFFFFF",
      "description": "Visa Signature",
      "issuer_name": "Chase"
    }
  },
  "created_at": "2026-01-15T10:31:00Z"
}

Get Enrollment

Retrieves an enrollment by ID.

GET

https://api.basistheory.com/agentic/enrollments/{enrollment_id}

Permissions

enrollment:get

Request

curl https://api.basistheory.com/agentic/enrollments/enr_wNe75VKdzvojI9iD5fJxr \
  -H 'BT-API-KEY: <BT_API_KEY>'

Request Parameters

Attribute	Required	Type	Description
enrollment_id	Yes	string	The ID of the enrollment to retrieve

Response

Returns an enrollment object if successful.

{
  "id": "enr_wNe75VKdzvojI9iD5fJxr",
  "provider": "visa",
  "status": "active",
  "card": {
    "brand": "visa",
    "bin": "424032",
    "last4": "0359",
    "expiration_month": 11,
    "expiration_year": 2029,
    "display": {
      "art_url": "https://assets.vims.visa.com/vims/cardart/abc123",
      "background_color": "1A1F71",
      "foreground_color": "FFFFFF",
      "description": "Visa Signature",
      "issuer_name": "Chase"
    }
  },
  "created_at": "2026-01-15T10:31:00Z"
}

Delete Enrollment

Deletes an enrollment.

DELETE

https://api.basistheory.com/agentic/enrollments/{enrollment_id}

Permissions

enrollment:delete

Request

curl -X DELETE https://api.basistheory.com/agentic/enrollments/enr_wNe75VKdzvojI9iD5fJxr \
  -H 'BT-API-KEY: <BT_API_KEY>'

Request Parameters

Attribute	Required	Type	Description
enrollment_id	Yes	string	The ID of the enrollment to delete

Response

Returns a 204 No Content response if successful.

Verify Enrollment

Enrollment verification is a multi-step flow that confirms the consumer owns the card. The @basis-theory/react-agentic SDK handles this entire flow automatically via the verifyEnrollment() method. The individual endpoints are documented below for reference.

For frontend integration, use the verifyEnrollment() method from the @basis-theory/react-agentic SDK's useBtAi hook. It handles the full verification UI including OTP entry and passkey creation. See the Agentic Credentials guide for usage examples.

Verification Flow

1. Start verification — POST /enrollments/:id/verify — returns available OTP methods (or auto-approves).
2. Select method — POST /enrollments/:id/verify/method — chooses SMS or email for OTP delivery.
3. Submit OTP — POST /enrollments/:id/verify/otp — submits the one-time code.
4. Complete — POST /enrollments/:id/verify/complete — finalizes verification after passkey creation.

Start Verification

Initiates the enrollment verification flow.

POST

https://api.basistheory.com/agentic/enrollments/{enrollment_id}/verify

Permissions

enrollment:verify

curl -X POST https://api.basistheory.com/agentic/enrollments/enr_wNe75VKdzvojI9iD5fJxr/verify \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "device_context": {
      "ip_address": "192.168.1.1"
    }
  }'

Returns either { "status": "approved" } if the enrollment is auto-approved, or a challenge response with available OTP methods:

{
  "status": "challenge",
  "methods": [
    { "id": "method_sms_001", "type": "sms", "value": "***-***-1234" },
    { "id": "method_email_001", "type": "email", "value": "j***@example.com" }
  ]
}

Select OTP Method

Selects which method (SMS or email) to use for OTP delivery.

POST

https://api.basistheory.com/agentic/enrollments/{enrollment_id}/verify/method

Permissions

enrollment:verify

curl -X POST https://api.basistheory.com/agentic/enrollments/enr_wNe75VKdzvojI9iD5fJxr/verify/method \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "method_id": "method_sms_001"
  }'

Returns confirmation that the OTP was sent:

{
  "status": "otp_sent",
  "method": {
    "id": "method_sms_001",
    "type": "sms",
    "value": "***-***-1234"
  }
}

Submit OTP

Submits the one-time code received by the consumer.

POST

https://api.basistheory.com/agentic/enrollments/{enrollment_id}/verify/otp

Permissions

enrollment:verify

curl -X POST https://api.basistheory.com/agentic/enrollments/enr_wNe75VKdzvojI9iD5fJxr/verify/otp \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "otp_code": "123456"
  }'

Returns a verified status if the OTP is correct. May return INVALID_OTP, OTP_EXPIRED, or MAX_ATTEMPTS_EXCEEDED errors.

Complete Verification

Finalizes verification after passkey creation on the consumer's device.

POST

https://api.basistheory.com/agentic/enrollments/{enrollment_id}/verify/complete

Permissions

enrollment:verify

curl -X POST https://api.basistheory.com/agentic/enrollments/enr_wNe75VKdzvojI9iD5fJxr/verify/complete \
  -H 'BT-API-KEY: <BT_API_KEY>'

After successful completion, the enrollment status changes from pending_verification to active.

Enrollment Object

Attribute	Type	Description
id	string	Unique identifier of the enrollment
provider	string	The network provider (visa or mastercard)
status	string	The enrollment status. See enrollment statuses
card	object	Card display metadata. See card object
created_at	string	ISO 8601 timestamp of when the enrollment was created

Enrollment Statuses

Status	Description
pending_verification	Awaiting consumer verification via OTP and passkey
active	Consumer verified; enrollment can be used to create instructions
suspended	Suspended by the card network (e.g., card reported lost or stolen)
deleted	Enrollment has been deleted

Card Object

Attribute	Type	Description
brand	string	Card brand (e.g., visa)
bin	string	Bank identification number (first 6 digits)
last4	string	Last four digits of the card number
expiration_month	integer	Card expiration month
expiration_year	integer	Card expiration year
display	object	Card art and display metadata. See display object

Display Object

Card art and display metadata from the card network.

Attribute	Type	Description
art_url	string	URL to the card art image
background_color	string	Hex color code for the card background
foreground_color	string	Hex color code for the card foreground
description	string	Card product description (e.g., "Visa Signature")
issuer_name	string	Name of the card issuer

Pagination

List endpoints use cursor-based pagination.

Attribute	Type	Description
pagination.next_cursor	string	Opaque cursor for the next page (absent when no more results)
pagination.has_more	boolean	Whether there are more results beyond this page

Pass next_cursor as the cursor query parameter to retrieve the next page.