> ## Documentation Index > Fetch the complete documentation index at: https://docs.lead.bank/llms.txt > Use this file to discover all available pages before exploring further. # Create a Card > > **Beta:** This endpoint is in beta and may change before general availability. Creates a new card. ## Business Rules - A new card is created in the `active` state. `status` is system-managed and cannot be set on create; status changes go through the status-transition endpoints. - `details.replacement_for` references an existing card that this card replaces. When provided, the referenced card must be in `closed` status at the time of the write and must not already be referenced by another card. ## Idempotency The Idempotency-Key header is required. Reusing a key with a different request body will return a 422 error. ## OpenAPI ````yaml POST /v0/cards openapi: 3.0.1 info: title: Lead Bank description: Lead Bank's APIs version: v1.0 servers: - url: https://api.sandbox.lead.bank - url: https://api.lead.bank security: - bearerAuth: [] tags: - name: ACH - name: Account Number - name: OAuth - name: Events - name: Instant Payments - name: Lending - name: Simulation - name: Internal Transfer - name: Disbursement - name: Entity - name: Wire - name: Originator - name: Funding - name: Balances - name: Compliance - name: UserAccount - name: Blockchain Payment paths: /v0/cards: post: tags: - Compliance summary: Create a card description: > > **Beta:** This endpoint is in beta and may change before general availability. Creates a new card. ## Business Rules - A new card is created in the `active` state. `status` is system-managed and cannot be set on create; status changes go through the status-transition endpoints. - `details.replacement_for` references an existing card that this card replaces. When provided, the referenced card must be in `closed` status at the time of the write and must not already be referenced by another card. ## Idempotency The Idempotency-Key header is required. Reusing a key with a different request body will return a 422 error. operationId: create-a-card parameters: - name: Idempotency-Key in: header required: true description: Unique key to ensure idempotent requests schema: type: string maxLength: 255 example: card-create-12345-abc requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCardRequest' examples: consumer_card: summary: Consumer card value: account_id: account_xyz123 entity_id: entity_xyz123 details: card_product_name: Rewards Visa is_virtual: false card_type: consumer expiry_date: '2029-01-31' last_four: '1234' metadata: {} replacement_card: summary: Replacement card for a closed card value: account_id: account_xyz123 entity_id: entity_xyz123 details: card_product_name: Rewards Visa is_virtual: false card_type: consumer expiry_date: '2029-01-31' last_four: '5678' replacement_for: card_old123 metadata: replacement_reason: lost responses: '200': description: Card created successfully. content: application/json: schema: $ref: '#/components/schemas/Card' '400': description: Malformed request or missing required header. content: application/json: schema: $ref: '#/components/schemas/APIError' examples: invalid_json: summary: Malformed JSON value: code: payload_invalid title: Your request body did not parse. detail: >- We couldn't parse your request body, please check that your request body is valid JSON. invalid_parameters: [] missing_idempotency_key: summary: Missing Idempotency-Key header value: code: operation_not_allowed title: This operation cannot be done on this object. detail: One or more request parameters failed validation invalid_parameters: - name: Idempotency-Key reason: >- parameter "Idempotency-Key" in header has an error: value is required but missing '401': description: Valid access token was not used to call the API. content: application/json: schema: $ref: '#/components/schemas/APIError' '403': description: Valid access token lacks the proper scopes. content: application/json: schema: $ref: '#/components/schemas/APIError' '422': description: Request validation failed. content: application/json: schema: $ref: '#/components/schemas/APIError' examples: missing_required_fields: summary: Missing required parameters value: code: parameters_invalid title: Your request parameters did not validate. detail: The request is well-formed but contains semantic errors. invalid_parameters: - name: account_id reason: missing - name: entity_id reason: missing replacement_for_target_not_closed: summary: replacement_for target is not in closed status value: code: parameters_invalid title: Your request parameters did not validate. detail: >- The card referenced by replacement_for must be in `closed` status at the time of the write. invalid_parameters: - name: details.replacement_for reason: target_not_closed replacement_for_conflict: summary: replacement_for target is already referenced value: code: parameters_invalid title: Your request parameters did not validate. detail: >- The card referenced by replacement_for is already referenced by another card. invalid_parameters: - name: details.replacement_for reason: target_already_replaced idempotency_mismatch: summary: Idempotency key reused with different request value: code: idempotency_request_inconsistent title: >- The request made does not match the previous request made with this idempotency key. detail: >- If you are trying to make a new request, then please update the idempotency key; otherwise, please use the same request body to make this request. invalid_parameters: [] '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/APIError' example: code: rate_limit_exceeded title: You've reached the rate limit for this call. detail: >- If you are continuously hitting rate limits please contact the Lead team. invalid_parameters: [] '500': description: Server error. Please try your request again. content: application/json: schema: $ref: '#/components/schemas/APIError' components: schemas: CreateCardRequest: type: object description: Request body for creating a new card. properties: account_id: $ref: '#/components/schemas/AccountID' entity_id: $ref: '#/components/schemas/EntityID' details: $ref: '#/components/schemas/CreateCardDetails' metadata: $ref: '#/components/schemas/Metadata' required: - account_id - entity_id - details Card: type: object description: A card object readOnly: true properties: id: $ref: '#/components/schemas/CardID' client_card_id: type: string readOnly: true description: | Client-provided identifier for the card. Optional: present only for cards created via file upload, and omitted for cards created through the API, which are identified solely by their server-generated ID. account_id: $ref: '#/components/schemas/AccountID' entity_id: $ref: '#/components/schemas/EntityID' status: $ref: '#/components/schemas/CardStatus' status_reason: type: string readOnly: true description: > The reason for the card's current status. Empty when the card is `active`; otherwise populated. Set via the status-transition endpoints. created_at: type: string format: date-time description: Creation timestamp. readOnly: true updated_at: type: string format: date-time description: Last update timestamp. readOnly: true details: $ref: '#/components/schemas/CardDetails' metadata: $ref: '#/components/schemas/Metadata' APIError: type: object properties: code: type: string description: The error code. title: type: string description: The error title. detail: type: string description: A detailed error description. status: type: string description: The HTTP status code. invalid_parameters: type: array description: Invalid request parameters with reasons, if applicable. items: $ref: '#/components/schemas/InvalidParameterDetail' instance: type: string description: >- The object causing this specific occurrence of the error, if applicable. AccountID: type: string description: The ID of the Account object. example: account_xyz123 pattern: ^account_\w+$ EntityID: type: string description: The ID of your entity. example: entity_xyz123 pattern: ^entity_[^\s]{1,33}$ CreateCardDetails: description: | Card details for a create request. Extends CardDetails, additionally requiring last_four (the API only creates cards that carry a PAN; the optional last_four on CardDetails is for responses, where file-ingested cards may have none). allOf: - $ref: '#/components/schemas/CardDetails' - type: object required: - last_four Metadata: type: object additionalProperties: type: string description: >- A set of key-value pairs that can be used to store additional information related to this object. CardID: type: string description: The server-generated ID of the Card object. example: card_xyz123 pattern: ^card_\w+$ CardStatus: type: string description: > Status is system-managed and cannot be set on create; status changes go through the status-transition endpoints. enum: - active - inactive - closed CardDetails: type: object description: Physical and product attributes of the card. properties: card_product_name: type: string description: The name of the card product in the partner's system. is_virtual: type: boolean description: >- True if the card exists as a virtual card; false if a physical representation of the card exists. card_type: $ref: '#/components/schemas/CardType' expiry_date: type: string format: date description: > ISO 8601 calendar date (YYYY-MM-DD) when the card expires. Always the last day of the expiration month (e.g. an expiration of 01/29 is `2029-01-31`). last_four: type: string description: > Last four digits of the card's PAN. Required when creating a card via the API; on responses it is omitted for cards that have no PAN on file (e.g. some file-ingested cards). pattern: ^[0-9]{4}$ example: '1234' replacement_for: allOf: - $ref: '#/components/schemas/CardID' description: > Optional. The server-generated ID (`card_*`) of the card this new card replaces. The referenced card must exist, must be in `closed` status at the time of the write, and must not already be referenced by another card. The system atomically sets `replaced_by` on the referenced card. closed_at: type: string format: date-time description: >- Timestamp when the card was closed. Present only when status is `closed`. readOnly: true required: - card_product_name - is_virtual - card_type - expiry_date InvalidParameterDetail: type: object properties: parameter: type: string description: Which parameter is invalid. example: transaction_type reason: type: string description: Why the parameter is invalid. CardType: type: string description: The product category the card belongs to. enum: - hsa - fsa - consumer - commercial securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````