Narmi cards API
The cards API from Narmi — 10 operation(s) for cards.
OpenAPI Specification
openapi: 3.0.3
info:
title: Narmi Public account balances cards API
version: v1
description: To read about Public API access and authentication, go to [API Overview](https://docs.narmi.com/docs/narmi-developer-docs/xl9dvbz84o11l-introduction).
termsOfService: https://www.narmi.com/policies/developer-terms-conditions
contact:
name: Narmi Support
email: support@narmi.com
servers:
- url: https://api.sandbox.narmi.dev/
description: ''
tags:
- name: cards
paths:
/v1/cards/:
get:
operationId: cards_list
description: "List the user's cards. \n\nAll monetary values are represented in minor units, or the smallest unit of the currency with no decimal (e.g., cents). For example, $10.00 is represented as 1000.\n\n\n\n<i>How can we improve these docs? <a href=\"mailto:docs+feedback@narmi.com\">Share your feedback.</a></i>"
summary: List cards for a user
parameters:
- name: page
required: false
in: query
description: A page number within the paginated result set.
schema:
type: integer
tags:
- cards
security:
- oauth2:
- read
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedCardInfoList'
examples:
READ:
value:
count: 123
next: http://api.example.org/accounts/?page=4
previous: http://api.example.org/accounts/?page=2
results:
- id: '1'
name: Standard Rewards
last_four_digits: '4692'
shipping:
address:
street_address: 96484 Donald Squares
street_address_2: ''
city: Lewishaven
region_code: MN
postal_code: '83505'
country_code: US
type: primary
method: ''
shipped_on: '2024-05-24'
network: Visa
state: normal
image: <svg>...</svg>
text_color: '#FFFFFF'
description: ''
'403':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
PermissionDenied:
value:
id: permission_denied
message: You do not have permission to perform this action.
description: ''
'404':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
NotFound:
value:
id: not_found
message: Not found.
description: ''
'500':
description: Server side error. Typically an issue related to connecting to the core or a third-party API.
x-stoplight:
id: wqvit71pccxzo
/v1/cards/{card_id}/:
get:
operationId: cards_retrieve
description: "Retrieve specified card. \n\nAll monetary values are represented in minor units, or the smallest unit of the currency with no decimal (e.g., cents). For example, $10.00 is represented as 1000.\n\n\n\n<i>How can we improve these docs? <a href=\"mailto:docs+feedback@narmi.com\">Share your feedback.</a></i>"
summary: Retrieve specified card
parameters:
- in: path
name: card_id
schema:
type: string
required: true
tags:
- cards
security:
- oauth2:
- read
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CardInfo'
examples:
READ:
value:
id: '1'
name: Standard Rewards
last_four_digits: '4692'
shipping:
address:
street_address: 96484 Donald Squares
street_address_2: ''
city: Lewishaven
region_code: MN
postal_code: '83505'
country_code: US
type: primary
method: ''
shipped_on: '2024-05-24'
network: Visa
state: normal
image: <svg>...</svg>
text_color: '#FFFFFF'
description: ''
'403':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
PermissionDenied:
value:
id: permission_denied
message: You do not have permission to perform this action.
description: ''
'500':
description: Server side error. Typically an issue related to connecting to the core or a third-party API.
x-stoplight:
id: 1kxqohlsv7zwo
put:
operationId: cards_update
description: "Activate and deactivate a specified card. \n\nAll monetary values are represented in minor units, or the smallest unit of the currency with no decimal (e.g., cents). For example, $10.00 is represented as 1000.\n\n\n\n<i>How can we improve these docs? <a href=\"mailto:docs+feedback@narmi.com\">Share your feedback.</a></i>"
summary: Activate or deactivate card
parameters:
- in: path
name: card_id
schema:
type: string
required: true
tags:
- cards
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CardRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/CardRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/CardRequest'
required: true
security:
- oauth2:
- write
deprecated: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/LegacyUpdateCardResponse'
examples:
Read:
value:
card:
id: card_id
core_user_id: '1'
bin: '123412'
last_four_digits: '1234'
state: active
svg: <svg>...</svg>
is_card_number_on_front: 'True'
card_text_color: '#FFFFFF'
description: ''
'403':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
PermissionDenied:
value:
id: permission_denied
message: You do not have permission to perform this action.
description: ''
'404':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
NotFound:
value:
id: not_found
message: Not found.
description: ''
'422':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
ErrorExample:
value:
id: invalid_request_error
message: state
description: ''
'406':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
NotAcceptable:
value:
id: not_acceptable
message: Deprecated update endpoint supports only versions <= 16.
description: Endpoint deprecated for version 17+
description: Endpoint deprecated for version 17+
'500':
description: Server side error. Typically an issue related to connecting to the core or a third-party API.
x-stoplight:
id: dxhbislydke4r
/v1/cards/{card_id}/address/:
get:
operationId: cards_address_retrieve
description: "Retrieve the registered address for the specified card. \n\nAll monetary values are represented in minor units, or the smallest unit of the currency with no decimal (e.g., cents). For example, $10.00 is represented as 1000.\n\n\n\n<i>How can we improve these docs? <a href=\"mailto:docs+feedback@narmi.com\">Share your feedback.</a></i>"
summary: Retrieve card address
parameters:
- in: path
name: card_id
schema:
type: string
required: true
tags:
- cards
security:
- oauth2:
- read
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Address'
examples:
READ:
value:
street_address: 96484 Donald Squares
street_address_2: ''
city: Lewishaven
region_code: MN
postal_code: '83505'
country_code: US
type: primary
description: ''
'403':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
PermissionDenied:
value:
id: permission_denied
message: You do not have permission to perform this action.
description: ''
'404':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
NotFound:
value:
id: not_found
message: Not found.
description: ''
'500':
description: Server side error. Typically an issue related to connecting to the core or a third-party API.
x-stoplight:
id: duivxf40ljmtj
/v1/cards/{card_id}/limits/:
get:
operationId: cards_limits_retrieve
description: "Get specified card limits. \n\nAll monetary values are represented in minor units, or the smallest unit of the currency with no decimal (e.g., cents). For example, $10.00 is represented as 1000.\n\n\n\n<i>How can we improve these docs? <a href=\"mailto:docs+feedback@narmi.com\">Share your feedback.</a></i>"
summary: Get specified card limits
parameters:
- in: path
name: card_id
schema:
type: string
required: true
tags:
- cards
security:
- oauth2:
- read
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CardLimits'
examples:
READ:
value:
id: '222'
pos_limit: 5000.0
atm_limit: 1000.0
has_atm_limit_increased_today: false
has_pos_limit_increased_today: false
can_user_request_limit_increase: true
description: ''
'403':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
PermissionDenied:
value:
id: permission_denied
message: User does not have the necessary card limit increase features.
description: ''
'404':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
NotFound:
value:
id: not_found
message: Not found.
description: ''
'500':
description: Server side error. Typically an issue related to connecting to the core or a third-party API.
x-stoplight:
id: pwdilhzyrbsyn
post:
operationId: cards_limits_create
description: "Update card limits. \n\nAll monetary values are represented in minor units, or the smallest unit of the currency with no decimal (e.g., cents). For example, $10.00 is represented as 1000.\n\n\n\n<i>How can we improve these docs? <a href=\"mailto:docs+feedback@narmi.com\">Share your feedback.</a></i>"
summary: Update card limits
parameters:
- in: path
name: card_id
schema:
type: string
required: true
tags:
- cards
security:
- oauth2:
- write
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CardLimits'
examples:
READ:
value:
id: '222'
pos_limit: 5000.0
atm_limit: 1000.0
has_atm_limit_increased_today: false
has_pos_limit_increased_today: false
can_user_request_limit_increase: true
description: ''
'400':
content:
application/json:
schema:
type: object
properties:
message:
type: string
id:
type: string
examples:
ValidationError:
value:
message: Requested limit must be greater than current limit
id: invalid
description: ''
'403':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: Unspecified response body
examples:
ErrorMaxRequestsExample:
value:
message: Maximum number of requests made
id: max_number_requests
ErrorATMPermissionExample:
value:
message: User does not have permission to increase atm limit
id: permission_denied
ErrorPOSPermissionExample:
value:
message: User does not have permission to increase spending limit
id: permission_denied
ErrorCardTypeATMPermissionExample:
value:
message: User does not have permission to update "atm" card type limits
id: permission_denied
ErrorCardTypeCreditPermissionExample:
value:
message: User does not have permission to update "credit" card type limits
id: permission_denied
description: ''
'404':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
NotFound:
value:
id: not_found
message: Not found.
description: ''
'422':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
ErrorInvalidRequestExample:
value:
id: invalid_request_error
message: amount
description: ''
'500':
description: Server side error. Typically an issue related to connecting to the core or a third-party API.
x-stoplight:
id: 3bjygpeehrwvy
/v1/cards/{card_id}/lock/:
post:
operationId: cards_lock_create
description: "Freeze a card so that it cannot be used. \n\nAll monetary values are represented in minor units, or the smallest unit of the currency with no decimal (e.g., cents). For example, $10.00 is represented as 1000.\n\n\n\n<i>How can we improve these docs? <a href=\"mailto:docs+feedback@narmi.com\">Share your feedback.</a></i>"
summary: Lock a card
parameters:
- in: path
name: card_id
schema:
type: string
required: true
tags:
- cards
security:
- oauth2:
- write
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CommonCard'
examples:
READ:
value:
id: '405'
core_user_id: gszAmFzCglfoGwyD
last_four_digits: 0058
state: normal
bin: '478763'
network: Visa
name: Standard Rewards
description: ''
'403':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
PermissionDenied:
value:
id: permission_denied
message: You do not have permission to perform this action.
description: ''
'404':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
NotFound:
value:
id: not_found
message: No card found for 1
description: ''
'500':
description: Server side error. Typically an issue related to connecting to the core or a third-party API.
x-stoplight:
id: bw0lkepmbwc55
/v1/cards/{card_id}/replace_card/:
post:
operationId: cards_replace_card_create
description: 'Submits a request to the card processor to send a replacement to the user, as well as notifying the user of said action via email.
All monetary values are represented in minor units, or the smallest unit of the currency with no decimal (e.g., cents). For example, $10.00 is represented as 1000.
<i>How can we improve these docs? <a href="mailto:docs+feedback@narmi.com">Share your feedback.</a></i>'
summary: Replace a missing card
parameters:
- in: path
name: card_id
schema:
type: string
required: true
tags:
- cards
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MissingCardRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/MissingCardRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/MissingCardRequest'
required: true
security:
- oauth2:
- write
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CommonCard'
examples:
READ:
value:
id: '405'
core_user_id: gszAmFzCglfoGwyD
last_four_digits: 0058
state: normal
bin: '478763'
network: Visa
name: Standard Rewards
description: ''
'400':
content:
application/json:
schema:
type: object
properties:
message:
type: string
id:
type: string
examples:
ValidationError:
value:
message: Please enter a valid reason.
id: invalid
description: ''
'403':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
PermissionDenied:
value:
id: permission_denied
message: You do not have permission to perform this action.
description: ''
'404':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
NotFound:
value:
id: not_found
message: Not found.
description: ''
'500':
description: Server side error. Typically an issue related to connecting to the core or a third-party API.
x-stoplight:
id: wiy6vrwdotcx7
/v1/cards/{card_id}/sensitive/:
get:
operationId: cards_sensitive_retrieve
description: 'Fetches card PAN, CVV, and Expiration Date.
All monetary values are represented in minor units, or the smallest unit of the currency with no decimal (e.g., cents). For example, $10.00 is represented as 1000.
<i>How can we improve these docs? <a href="mailto:docs+feedback@narmi.com">Share your feedback.</a></i>'
summary: Retrieve card PAN
parameters:
- in: path
name: card_id
schema:
type: string
required: true
tags:
- cards
security:
- oauth2:
- read
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SensitiveCardInfo'
description: ''
'404':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
NotFound:
value:
id: not_found
message: No card found for 1
description: ''
'500':
description: Server side error. Typically an issue related to connecting to the core or a third-party API.
x-stoplight:
id: cdq8iiws8zupy
/v1/cards/{card_id}/subscriptions/:
get:
operationId: cards_subscriptions_retrieve
description: 'Retrieve card subscriptions for a specified card.
All monetary values are represented in minor units, or the smallest unit of the currency with no decimal (e.g., cents). For example, $10.00 is represented as 1000.
<i>How can we improve these docs? <a href="mailto:docs+feedback@narmi.com">Share your feedback.</a></i>'
summary: Retrieve card subscriptions
parameters:
- in: path
name: card_id
schema:
type: string
description: The id of the card to fetch subscriptions for.
required: true
- in: query
name: end_date
schema:
type: string
format: date
default: '2026-07-17'
description: Optional `end_date` parameter. The end date for card subscriptions (YYYY-MM-DD).
- in: query
name: start_date
schema:
type: string
format: date
default: '2025-07-17'
description: Optional `start_date` parameter. The start date for card subscriptions (YYYY-MM-DD).
tags:
- cards
security:
- oauth2:
- read
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CardSubscriptionsAndTransactions'
examples:
READ:
value:
subscriptions:
- id: 8c082ea3-00a4-4881-b38a-b6487ba93a52
amount: 10.0
merchant_name: Spotify
state: current
recurrence_frequency: monthly
next_payment_date: '2024-06-01'
- id: 17cc8bdc-5d5f-4026-8109-c93b82e5e5ba
amount: 2.99
merchant_name: Apple
state: cancelled
recurrence_frequency: monthly
next_payment_date: null
monthly_transactions:
- month: 2024-03
total: 12.99
transaction_count: 2
transactions:
- id: cb10f8c0-bfbd-406a-9df9-f0dcc92e9dfc
amount: '10.00'
category_code: '1234'
merchant_name: Spotify
transaction_date: '2024-03-01'
subscription_id: 8c082ea3-00a4-4881-b38a-b6487ba93a52
- id: dbed8914-6935-4e3c-bcb6-4eed42dc2751
amount: '2.99'
merchant_name: Apple
category_code: '5678'
transaction_date: '2024-03-10'
subscription_id: 17cc8bdc-5d5f-4026-8109-c93b82e5e5ba
- month: 2024-04
total: 12.99
transaction_count: 2
transactions:
- id: 9c19c5d9-96df-40a7-93d4-83daf55308d2
amount: '10.00'
category_code: '1234'
merchant_name: Spotify
transaction_date: '2024-04-01'
subscription_id: 8c082ea3-00a4-4881-b38a-b6487ba93a52
- id: d5e0930a-efc0-422e-b63c-d89346eae4a8
amount: '2.99'
merchant_name: Apple
category_code: '5678'
transaction_date: '2024-04-10'
subscription_id: 17cc8bdc-5d5f-4026-8109-c93b82e5e5ba
- month: 2024-05
total: 10.0
transaction_count: 1
transactions:
- id: e81f51fc-23ee-4b2c-8e71-1abd5866a01d
amount: '10.00'
category_code: '1234'
merchant_name: Spotify
transaction_date: '2024-05-01'
subscription_id: 8c082ea3-00a4-4881-b38a-b6487ba93a52
description: ''
'400':
content:
application/json:
schema:
type: object
properties:
message:
type: string
id:
type: string
examples:
ValidationError:
value:
message: Invalid input.
id: invalid
description: ''
'403':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: Unspecified response body
examples:
ErrorCardSubscriptionPermissionExample:
value:
message: User does not have the necessary card subscription management feature.
id: permission_denied
ErrorCardPermissionExample:
value:
message: User does not have the "cards" feature.
id: permission_denied
description: ''
'404':
content:
application/json:
schema:
type: object
properties:
id:
type: string
message:
type: string
examples:
NotFound:
value:
id: not_found
message: Not found.
description: ''
'500':
content:
application/json:
schema:
type: object
additionalProperties: {}
description: Unspecified response body
examples:
VisaExceptionError:
value:
id: service_failure_error
message: Sorry, we were unable to process your request, please check back soon.
description: ''
x-stoplight:
id: insbbgsoclbop
/v1/cards/{card_id}/travel_note/:
get:
operationId: cards_travel_note_list
description: 'List the travel notices for the specified card.
All monetary values are represented in minor units, or the smallest unit of the currency with no decimal (e.g., cents). For example, $10.00 is represented as 1000.
<i>How can we improve these docs? <a href="mailto:docs+feedback@narmi.com">Share your feedback.</a></i>'
summary: Get a card's travel notice
parameters:
- in: path
name: card_id
schema:
type: string
pattern: ^[0-9A-Za-z-]+$
required: true
- name: page
required: false
in: query
description: A page number within the paginated result set.
schema:
type: integer
tags:
- cards
security:
- oauth2:
- read
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedCardTravelNoteList'
description: ''
'403':
content:
application/json:
schema:
type: object
properties:
id:
# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/narmi/refs/heads/main/openapi/narmi-cards-api-openapi.yml