---
title: "Create a card issuing request"
method: POST
path: "/v1/card_issuing_requests"
tags: ["Card issuing request"]
---

# Create a card issuing request

`POST /v1/card_issuing_requests`

## Request

- Base URL: `https://api.cardda.com`
- URL: `https://api.cardda.com/v1/card_issuing_requests`
- Auth: HTTP bearer

Creates a card issuing request. Requires the caller to be a member of the
target company **and** either an admin or hold the `card_issuing_requests_manage`
permission.

On creation the request runs an eligibility check
(`Cards::CardIssuingEligibilityChecker`); if it fails, the endpoint returns
`422` with `{ "message": <first error>, "errors": [...] }`.

For physical CLP cards, `recipient_name` and `shipping_address` are required
(model validation). `budget_cents` must be ≥ 1 and `budget_currency` a valid
ISO-4217 currency.

## Parameters

- `#/paths/~1v1~1merchants/get/parameters/0` (unresolved $ref)

## Request body

- CardIssuingRequestCreate: Payload to create a card issuing request. `budget_cents` and `budget_currency` are validated by the model (budget must be ≥ 1 and a valid ISO-4217 currency). Physical CLP requests additionally require `recipient_name` and `shipping_address`.
  - `name` string: Display name for the card.
  - `user_id` string, required: Firebase user id of the future cardholder. Must belong to `company_id`.
  - `company_id` string, uuid, required: UUID of the company the card belongs to.
  - `budget_cents` integer, required: Requested spending budget in cents. Must be at least 1.
  - `budget_currency` string, required: ISO-4217 code of the budget currency. Must be a valid currency.
  - `interval` 'monthly' | 'daily': Budget renewal interval. Defaults to `monthly`.
  - `physical` boolean: Request a physical card. Defaults to `false`. Cannot be changed after creation.
  - `purchase` 'national' | 'international' | 'both': Allowed purchase geography.
  - `recipient_name` string: Recipient full name. Required for physical CLP requests.
  - `contact_phone` string: Contact phone for the physical shipment.
  - `shipping_address` object: Shipping address. Required for physical CLP requests.
    - `street` string
    - `number` string
    - `municipality_id` integer
    - `complement` string
  - `status` 'pending' | 'accepted' | 'declined' | 'printing' | 'printed' | 'sent' | 'delivered': Initial status. **Admin-only** — ignored for non-admin callers.

## Response `201`

The created card issuing request.

- CardIssuingRequest: A single user's request to issue a `VendorCard`. When a user creates a card in the dashboard, a `CardIssuingRequest` is created first; once approved by Cardda staff (or auto-issued) it produces the actual card and `vendor_card_id` is set.
  - `id` string, uuid
  - `name` string, nullable: Display name requested for the card.
  - `user_id` string: Firebase user id of the future cardholder (not a UUID).
  - `company_id` string, uuid
  - `status` 'pending' | 'accepted' | 'declined' | 'printing' | 'printed' | 'sent' | 'delivered': Lifecycle of the request. - `pending` — created, awaiting approval / issuing. - `accepted` — a card was issued and linked (`vendor_card_id` is set). - `declined` — rejected. - `printing` / `printed` — physical card in production. - `sent` — dispatched to the cardholder (admin marks this). - `delivered` — cardholder self-confirmed receipt (see `confirm_delivery`).
  - `budget_cents` integer: Requested spending budget in cents, in `budget_currency`.
  - `budget_currency` string: ISO-4217 code of the requested budget currency.
  - `interval` 'monthly' | 'daily': Budget renewal interval for the resulting card.
  - `physical` boolean: Whether a physical (plastic) card is requested. `false` for virtual-only.
  - `purchase` 'national' | 'international' | 'both', nullable: Allowed purchase geography for the card.
  - `vendor_id` string, nullable: Issuing partner selected at approval time (e.g. `plh`, `pomelo`, `slash`).
  - `vendor_card_id` string, nullable: Id of the issued `VendorCard` once the request is accepted (vendor-prefixed string, not a UUID).
  - `type` string, nullable: STI subclass derived from `vendor_id` (e.g. `Cards::Plh::Request`).
  - `recipient_name` string, nullable: Recipient full name for physical shipments. Required for physical CLP requests.
  - `contact_phone` string, nullable: Contact phone for the physical shipment.
  - `shipping_address` object, nullable: Shipping address for physical CLP requests. `municipality_name` is enriched server-side from `municipality_id`.
    - `street` string
    - `number` string
    - `municipality_id` integer
    - `municipality_name` string
    - `complement` string, nullable
  - `shipping_municipality_name` string, nullable: Resolved municipality name for the shipping address (computed field).
  - `kyc_completed` boolean: Whether the owning company has completed KYC. Computed field. Serialized as the JSON key `kyc_completed` (the `?` Ruby predicate suffix is stripped).
  - `tracking_number` string, nullable: Carrier tracking number (staff-set). Only present for dispatched physical cards.
  - `tracking_url` string, nullable: Carrier tracking URL (staff-set).
  - `estimated_delivery_date` string, date, nullable: Estimated delivery date (staff-set).
  - `shipment_id` string, nullable: Vendor shipment identifier for physical cards.
  - `printing_at` string, date-time, nullable: When the request entered the `printing` milestone.
  - `sent_at` string, date-time, nullable: When the physical card was dispatched.
  - `delivered_at` string, date-time, nullable: When the cardholder confirmed delivery.
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `401`: Unauthorized — missing or invalid bearer token, or the caller is not an admin/manager of the target company (Pundit authorization failure). Returned with an empty body.
- `422`: Unprocessable Entity — eligibility check failed or model validation failed (e.g. budget below 1, invalid currency, missing shipping data for a physical CLP card). Body: `{ "message": ..., "errors": [...] }`.

---

[API](https://skmtc.dev/cardda/apis/cards-api.md) - [All operations](https://skmtc.dev/cardda/apis/cards-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardda/apis/cards-api/revisions/c57a213e5752?raw)