> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clara.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Provision Cards for Employees

> Look up or create a user, issue a virtual card with a spending limit, apply restrictions, and clean up when they leave.

This guide covers the full employee card lifecycle: onboarding a new cardholder, issuing a virtual card, configuring optional spending restrictions, and safely offboarding when an employee departs.

## Prerequisites

* A valid Bearer token and mTLS client certificate. See [Authentication](/authentication).
* The employee's name, email, and role.

***

## Step 1: Look up the user

Before creating a card, check whether the user already exists in Clara. Query by email to avoid duplicates.

```bash theme={null}
curl --request GET \
  "https://public-api.mx.clara.com/api/v3/users?email=ana.garcia@acme.com" \
  --header "Authorization: Bearer <TOKEN>" \
  --cert client.crt \
  --key client.key
```

Response:

```json theme={null}
{
  "totalElements": 1,
  "content": [
    {
      "uuid": "a0c82a20-ac09-4cfd-b429-d0623585911e",
      "fullName": "Ana García",
      "email": "ana.garcia@acme.com",
      "role": "EMPLOYEE",
      "status": "ACTIVE"
    }
  ]
}
```

If `totalElements` is `0`, the user doesn't exist yet — create them first via the [Users API](/v3/users), then proceed with the `uuid` returned.

***

## Step 2: Issue a virtual card

Create a virtual card assigned to the user. Set a `threshold` (spending limit) and a `periodicity` that resets it automatically.

```bash theme={null}
curl --request POST \
  "https://public-api.mx.clara.com/api/v3/cards" \
  --header "Authorization: Bearer <TOKEN>" \
  --header "Content-Type: application/json" \
  --cert client.crt \
  --key client.key \
  --data '{
    "type": "VIRTUAL",
    "alias": "Ana García — Travel",
    "userUuid": "a0c82a20-ac09-4cfd-b429-d0623585911e",
    "threshold": 5000,
    "periodicity": "MONTHLY"
  }'
```

Response:

```json theme={null}
{
  "uuid": "5d1e2f83-1c90-4c34-9400-bfef9ac85c6e",
  "alias": "Ana García — Travel",
  "status": { "code": "ACTIVE", "description": "Active" },
  "maskedPan": "514509******5946",
  "threshold": 5000,
  "periodicity": { "type": "MONTHLY" },
  "type": { "format": "VIRTUAL" },
  "user": {
    "uuid": "a0c82a20-ac09-4cfd-b429-d0623585911e",
    "name": "Ana García"
  }
}
```

Save the card `uuid` — you'll need it for configuration and status checks.

| Field          | Notes                                                              |
| -------------- | ------------------------------------------------------------------ |
| `type`         | `VIRTUAL` or `PHYSICAL`                                            |
| `alias`        | A human-readable label shown in the Clara dashboard                |
| `threshold`    | Amount in your company's currency (MXN, BRL, or COP)               |
| `periodicity`  | `MONTHLY`, `WEEKLY`, or `DAILY` — determines when the limit resets |
| `businessType` | Optional: `BUSINESS` or `WORLD_ELITE`                              |

***

## Step 3: Apply spending restrictions (optional)

Use the Card Configurations API to add time, day-of-week, or merchant category restrictions. All fields are optional and can be combined.

```bash theme={null}
curl --request POST \
  "https://public-api.mx.clara.com/api/v2/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e/configurations" \
  --header "Authorization: Bearer <TOKEN>" \
  --header "Content-Type: application/json" \
  --cert client.crt \
  --key client.key \
  --data '{
    "weekdays": {
      "values": ["SATURDAY", "SUNDAY"],
      "allowedDaysOfUse": false
    },
    "merchants": {
      "values": ["TRANSPORTATION", "CAR_RENTALS", "TRAVEL_AND_LODGING", "FOOD"],
      "allowedMerchants": true
    }
  }'
```

This example restricts usage to weekdays only and allows spending solely at transportation, car rental, hotel, and food merchants.

Common configurations:

| Restriction                         | How                                                                 |
| ----------------------------------- | ------------------------------------------------------------------- |
| Block weekends                      | `weekdays.values: ["SATURDAY","SUNDAY"]`, `allowedDaysOfUse: false` |
| Restrict to specific MCC categories | `merchants.values: [...]`, `allowedMerchants: true`                 |
| Time window (e.g., 9am–6pm)         | `period.startTime: "09:00"`, `endTime: "18:00"`                     |
| Auto-delete after a trip            | `period.endDate: "YYYY-MM-DD"`, `enableAutoDeletion: true`          |

See [Card Configurations](/v2/card-configurations) for the full list of merchant categories and options.

***

## Step 4: Confirm the card is active

Verify the card is ready before distributing it to the employee.

```bash theme={null}
curl --request GET \
  "https://public-api.mx.clara.com/api/v3/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e" \
  --header "Authorization: Bearer <TOKEN>" \
  --cert client.crt \
  --key client.key
```

Confirm `status.code` is `"ACTIVE"` before sharing the card details with the cardholder.

***

## Adjust the spending limit

To raise or lower the threshold at any time:

```bash theme={null}
curl --request PATCH \
  "https://public-api.mx.clara.com/api/v3/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e/threshold" \
  --header "Authorization: Bearer <TOKEN>" \
  --header "Content-Type: application/json" \
  --cert client.crt \
  --key client.key \
  --data '{ "threshold": 8000 }'
```

***

## Offboarding

When an employee leaves, first lock the card to immediately block usage, then delete it once you've confirmed there are no pending transactions.

**Lock the card** (immediately blocks all charges):

```bash theme={null}
curl --request PATCH \
  "https://public-api.mx.clara.com/api/v3/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e/lock" \
  --header "Authorization: Bearer <TOKEN>" \
  --header "Content-Type: application/json" \
  --cert client.crt \
  --key client.key \
  --data '{ "lockCode": 16 }'
```

**Delete the card** (permanent, cannot be recovered):

```bash theme={null}
curl --request DELETE \
  "https://public-api.mx.clara.com/api/v3/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e" \
  --header "Authorization: Bearer <TOKEN>" \
  --cert client.crt \
  --key client.key
```

<Warning>
  Deleted cards cannot be recovered. Lock first, wait 24–48 hours to confirm no settlements are pending, then delete.
</Warning>

***

## Related

* [Cards API reference](/v3/cards)
* [Users API reference](/v3/users)
* [Card Configurations reference](/v2/card-configurations)