> ## Documentation Index > Fetch the complete documentation index at: https://docs.synctera.com/llms.txt > Use this file to discover all available pages before exploring further. # List Cards > List of cards matching query parameters ## OpenAPI ````yaml openapi.json get /cards openapi: 3.0.3 info: description: >- This is the official reference documentation for Synctera APIs. If you need something specific or have a question, contact us.

license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html title: Synctera API version: 0.217.0 servers: - description: Sandbox (no real world financial impact) url: https://api-sandbox.synctera.com/v0 - description: Production url: https://api.synctera.com/v0 security: - bearerAuth: [] tags: - description: Lookup merchant information name: Merchants - description: Requests to generate simulated webhooks name: Card Webhook Simulations - description: >- Account programs define configurations for payment rails and transaction capabilities across different account types. name: Account Programs - description: Simulate receiving ACH transactions and returns name: ACH Transaction Simulations - description: Requests for risk evaluation and decisioning name: Risk Evaluations - description: Requests to link and manage External Cards name: External Cards - description: | The disclosures resource is used to track the status of disclosures and ensure that all parties have been shown the necessary disclosures to meet regulatory obligations. name: Disclosures - description: Create and manage Cash Order and Cash Deposit transfers name: Cash Orders and Deposits (alpha) - description: Requests to initiate customer verification. name: KYC Verification (deprecated) - description: Request to create and manage users name: Users - description: See balance history name: BalanceHistory - description: >- Migration mappings associate resources from an old tenant identity with a new tenant identity. name: Migration Mappings - description: | The External Account resource is used for managing links to accounts that operate outside of the Synctera ecosystem. name: External Accounts - description: Requests to create and manage account products, including fees, interest. name: Account Products - description: Requests to create and manage webhooks name: Webhooks - description: Create and manage documents. name: Documents - description: >- Create and manage same currency and multi-currency international wire transfers name: International Wires (alpha) - description: Requests for transaction risk detection name: Transaction risk - description: >- Used to configure bank accounts for which synctera accounts are considered a "subledger" to name: Bank Account - description: Request to create and manage party groups and party group members name: Party Groups - description: Requests to manage addresses name: Addresses - description: Requests to manage monitoring subscriptions and alerts for customers. name: Monitoring - description: Requests to search and manage compliance searches name: Compliance Searches - description: Requests to create and manage customers name: Customers - description: | The internal account resource is used for managing links to internal accounts where the funds are managed by integrators. name: Internal Accounts - description: Create and manage spending controls name: Spend Controls - description: Retrieve user identity information name: Identity - description: Requests to manage banks name: Banks - description: | The Disclosures resource is used to track the status of disclosures and ensure that customers have been shown the necessary disclosures to meet regulatory obligations. name: Disclosures (deprecated) - description: Create and manage wire transfers name: Wires - description: Requests to issue and manage Cards name: Cards - description: Request to create and manage edd name: Trust - description: Request to enroll, renew, or cancel watchlist monitors name: Watchlist (deprecated) - description: Endpoints for modifying or fetching posting dates name: Posting Dates - description: Transaction lines API name: transactions - description: Request to create and manage accounts name: Accounts - description: Requests to create and manage notes name: Notes - description: Account Template name: Account Templates - description: API for effective balances name: effective_balances - description: Requests to create and manage personal ID configurations name: Personal ID Configuration - description: > A natural person (individual human) that is relevant to the Synctera platform in some way: e.g. a personal customer or a director/officer/owner of a business. name: Persons - description: > Represents the relationships between parties. A relationship can exist between personal customers, business customers, or non-customer persons/organizations. name: Relationships - description: > A legal entity (corporation, partnership, etc.) that is relevant to the Synctera platform in some way: a business customer or some other organization that has an ownership share in such a business customer. name: Businesses - description: Request to create and manage payment_schedules name: Cronut - description: Requests to manage partners name: Partners - description: Request to create and manage deposits using remote deposit capture name: Remote Check Deposit - description: Requests to create and manage API keys name: API Keys - description: Requests to create and manage ban rules name: Ban Rules - description: Admin API for Middesk configuration using the tenants API keys. name: Middesk - description: Request to create and manage exclusions name: Stately - description: Request to create and manage partner configurations name: Quickstart - description: Manage contacts for bank and fintech partners name: Contacts - description: Create and manage transactions name: Transactions - description: Request to create and manage rdc configurations name: RDC Config - description: Create and manage holds name: Hold - description: Requests to create and manage roles name: Roles - description: Simulate receiving Wire transactions and returns name: Wire Transaction Simulations - description: Requests to create licenses name: Licenses - description: Requests to Admins to grant permissions to user name: Request Permissions - description: Configure vendor secrets for egress requests name: Egress Gateway Vendor Secret CRUD API - description: Requests to screen parties against sanctions watchlists name: Sanctions Screening - description: Create and manage payments name: ACH - description: Requests to calculate and manage CRR name: CRR - description: Requests to search financial institutions name: Institutions (Beta) - description: Create and manage tenant configurations name: Tenant Configs - description: Create and manage sweep configurations name: Configs - description: > Represents the compliance rules that are used to verify certain kinds of money movement. name: Compliance Rules - description: Configure webhook secrets for egress requests name: Egress Gateway Webhook Secret CRUD API - description: Create and manage transactions name: Transactions (internal) - description: History name: History - description: Create and manage EFT Canada transfers name: EFT Canada (Beta) - description: Requests to generate simulated transactions name: Card Transaction Simulations - description: Requests to initiate customer verification. name: KYC/KYB Verifications paths: /cards: summary: Cards description: | The Card object represents your customer's spending card. get: tags: - Cards summary: List Cards description: | List of cards matching query parameters operationId: listCards parameters: - $ref: '#/components/parameters/last_four_query' - $ref: '#/components/parameters/postal_code_query' - $ref: '#/components/parameters/customer_id_query' - $ref: '#/components/parameters/card_brand_query' - $ref: '#/components/parameters/bin_prefix_query' - $ref: '#/components/parameters/emboss_name_query' - $ref: '#/components/parameters/card_type_query' - $ref: '#/components/parameters/form_query' - $ref: '#/components/parameters/page_token' - $ref: '#/components/parameters/card_status_query' - $ref: '#/components/parameters/card_product_id_query' - $ref: '#/components/parameters/account_id_query_array' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/barcode_query' - $ref: '#/components/parameters/expiration_date_query' - $ref: '#/components/parameters/card_sort_by_query' responses: '200': content: application/json: schema: $ref: '#/components/schemas/card_list_response' description: Cards '400': $ref: '#/components/responses/bad_request' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '422': $ref: '#/components/responses/unprocessable_entity' '500': $ref: '#/components/responses/internal_server_error' components: parameters: last_four_query: description: The last 4 digits of the card PAN in: query name: last_four schema: example: '1234' pattern: ^\d{4}$ type: string postal_code_query: description: The postal code of a card user in: query name: postal_code schema: example: '49633' type: string customer_id_query: in: query name: customer_id schema: $ref: '#/components/schemas/customer_id1' card_brand_query: description: The brand of a card product in: query name: card_brand schema: $ref: '#/components/schemas/card_brand' bin_prefix_query: in: query name: bin_prefix schema: $ref: '#/components/schemas/bin_prefix' emboss_name_query: description: emboss name in: query name: emboss_name schema: type: string card_type_query: description: Indicates the type of card in: query name: card_type schema: $ref: '#/components/schemas/card_type' form_query: description: The format of the card in: query name: form schema: $ref: '#/components/schemas/form' page_token: in: query name: page_token schema: description: >- Optional pagination token to be provided to retrieve subsequent pages, returned from previous get example: a8937a0d type: string card_status_query: description: The status of a card in: query name: card_status schema: $ref: '#/components/schemas/card_status' card_product_id_query: in: query name: card_product_id schema: $ref: '#/components/schemas/card_product_id' account_id_query_array: description: Account ID(s). Multiple IDs can be provided as a comma-separated list. explode: false in: query name: account_id schema: items: $ref: '#/components/schemas/account_id' type: array style: form limit: in: query name: limit schema: default: 100 description: > Maximum number of objects to return per page. If the limit is greater than 100, then it will be set to 100. example: 100 minimum: 1 type: integer barcode_query: in: query name: barcode schema: $ref: '#/components/schemas/barcode' expiration_date_query: description: The date representing when the card would expire at in: query name: expiration_date schema: example: '2006-01-02' format: date type: string card_sort_by_query: description: | Specifies the sort order for the returned cards. explode: false in: query name: sort_by schema: items: enum: - account_id:asc - account_id:desc - card_brand:asc - card_brand:desc - card_product_id:asc - card_product_id:desc - card_status:asc - card_status:desc - card_type:asc - card_type:desc - customer_id:asc - customer_id:desc - expiration_date:asc - expiration_date:desc - form:asc - form:desc - last_four:asc - last_four:desc type: string type: array style: form schemas: card_list_response: allOf: - $ref: '#/components/schemas/paginated_response' - properties: cards: description: Array of Cards items: $ref: '#/components/schemas/card_response' type: array required: - cards type: object customer_id1: description: The unique identifier of a customer example: 7d943c51-e4ff-4e57-9558-08cab6b963c7 format: uuid type: string card_brand: description: The brand of a card product enum: - MASTERCARD - VISA type: string bin_prefix: description: The BIN number that prefixes a card PAN (first 6 or 8 digits) example: 123456 pattern: ^(\d{6}|\d{8})$ type: string card_type: description: The type of the card program and BIN enum: - DEBIT - PREPAID type: string form: description: PHYSICAL or VIRTUAL. enum: - PHYSICAL - VIRTUAL type: string card_status: description: The status indicating the card lifecycle state enum: - ACTIVE - IMAGE_PENDING - IMAGE_REJECTED - PENDING - REJECTED - SUSPENDED - TERMINATED - UNACTIVATED title: Card Status type: string card_product_id: description: The unique identifier of a cards product example: 7d943c51-e4ff-4e57-9558-08cab6b963c7 format: uuid type: string account_id: description: The unique identifier of an account example: 7d943c51-e4ff-4e57-9558-08cab6b963c7 format: uuid type: string barcode: description: The barcode associated with a card example: 10044461864615598000 pattern: \d{20} type: string paginated_response: properties: next_page_token: description: >- If returned, use the next_page_token to query for the next page of results. Not returned if there are no more rows. example: a8937a0d type: string title: Paginated List response type: object card_response: discriminator: mapping: PHYSICAL: $ref: '#/components/schemas/physical_card_response' VIRTUAL: $ref: '#/components/schemas/virtual_card_response' propertyName: form oneOf: - $ref: '#/components/schemas/virtual_card_response' - $ref: '#/components/schemas/physical_card_response' error: description: >- Synctera error responses in API v0 follow [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807). Following that standard, the field for a machine-readable "error code" in API v0 is `type`. In our future API v1, we are phasing out RFC 7807 and adopting a custom error format. That format will be documented in our API v1 spec. But you may see some v0 error responses with a machine-readable `code` field while we are making the transition from v0 to v1. properties: code: description: >- An optional “sneak preview” of our future API v1 error responses. This is provided to give integrators a chance to work with our future error codes. Error codes for the same error may change between v0 and v1. example: BAD_REQUEST_BODY type: string detail: description: | A human-readable string explaining this particular error. example: 'missing required fields: first_name, dob' type: string status: description: the HTTP status code for this response example: 400 type: integer title: description: > A human-readable string for this general category of error, which corresponds 1-to-1 with error types (`title` is the human-readable version of `type`). There can be multiple distinct titles for the same HTTP status code, and the same `title` can result in many different `detail` strings. This field will be removed in API v1. example: Bad Request Body type: string type: description: > A machine-readable string that identifies the error for programmatic use. This is a URI, i.e. a globally unique identifier. It is _not_ necessarily a URL, so do not expect it to resolve to a web page. You can use this whole string as an error code, or just everything after the last slash. This field will be removed in API v1. example: https://dev.synctera.com/errors/bad-request-body type: string title: Standard error response (RFC 7807 problem report) type: object physical_card_response: allOf: - $ref: '#/components/schemas/physical_card_plus_status' - properties: bin: description: The bin number type: string card_brand: $ref: '#/components/schemas/card_brand' physical_card_format: $ref: '#/components/schemas/physical_card_format' tenant: $ref: '#/components/schemas/tenant_id' required: - account_id - card_brand - card_product_id - creation_time - emboss_name - form - id - physical_card_format - shipping - tenant - type type: object title: Physical Card virtual_card_response: allOf: - $ref: '#/components/schemas/virtual_card_plus_status' - properties: bin: description: The bin number type: string card_brand: $ref: '#/components/schemas/card_brand' tenant: $ref: '#/components/schemas/tenant_id' required: - account_id - card_brand - card_product_id - creation_time - emboss_name - expiration_month - expiration_year - form - id - last_four - tenant - type type: object title: Virtual Card physical_card_plus_status: allOf: - $ref: '#/components/schemas/physical_card' - $ref: '#/components/schemas/physical_card_response_status' physical_card_format: description: The format of a physical card product enum: - CHIP - CONTACT - CONTACTLESS - MAGNETIC_STRIPE - PHYSICAL_COMBO type: string tenant_id: description: > The id of the tenant containing the resource. This is relevant for Fintechs that have multiple workspaces. example: abcdef_ghijkl type: string virtual_card_plus_status: allOf: - $ref: '#/components/schemas/virtual_card_response_status' - $ref: '#/components/schemas/virtual_card' physical_card: allOf: - $ref: '#/components/schemas/base_card' - properties: card_image_id: description: The ID of the custom card image used for this card example: 7d943c51-e4ff-4e57-9558-08cab6b963c7 format: uuid type: string shipping: $ref: '#/components/schemas/shipping' type: object description: Details pertaining to issuing a new physical card title: Physical Card physical_card_response_status: allOf: - $ref: '#/components/schemas/card_status_object' - properties: card_fulfillment_status: $ref: '#/components/schemas/card_fulfillment_status' fulfillment_details: $ref: '#/components/schemas/fulfillment_details' tracking_number: deprecated: true description: > This contains all shipping details as provided by the card fulfillment provider, including the tracking number. This field is deprecated. Instead, please use the fulfillment_details object, which includes a field for just the tracking number. example: >- Ship Date [2022-07-19], Shipping Method [UPS Next Day Air Saver]; Tracking Number [1ZW3268W1319325382] readOnly: true type: string required: - card_fulfillment_status - card_status - status_reason type: object virtual_card_response_status: allOf: - required: - card_status - status_reason type: object - $ref: '#/components/schemas/card_status_object' virtual_card: allOf: - $ref: '#/components/schemas/base_card' description: A virtual card title: Virtual Card base_card: allOf: - properties: account_id: description: The ID of the account to which the card will be linked example: 7d943c51-e4ff-4e57-9558-08cab6b963c7 format: uuid type: string business_id: description: >- The business ID associated with this card. If no customer_id is supplied, a card can still be issued to a business, but cannot be activated or used until a customer is assigned via the PATCH /cards/{card_id} endpoint. example: 7d943c51-e4ff-4e57-9558-08cab6b963c7 format: uuid type: string card_product_id: description: The card product to which the card is attached example: 7d943c51-e4ff-4e57-9558-08cab6b963c7 format: uuid type: string creation_time: description: >- The timestamp representing when the card issuance request was made example: '2010-05-06T12:23:34.321Z' format: date-time readOnly: true type: string customer_id: description: >- The ID of the customer to whom the card will be issued. If a business_id is passed, but a customer_id not passed at the time of card creation the card cannot be activated or used for spend until it's assigned to a human customer via the PATCH /cards/{card_id} endpoint. If no business_id is passed, a customer_id is required. example: 7d943c51-e4ff-4e57-9558-08cab6b963c7 format: uuid type: string emboss_name: $ref: '#/components/schemas/emboss_name' expiration_month: example: '06' readOnly: true type: string expiration_time: description: The timestamp representing when the card would expire at example: '2010-05-06T12:23:34.321Z' format: date-time readOnly: true type: string expiration_year: example: '25' readOnly: true type: string id: description: Card ID example: 7d943c51-e4ff-4e57-9558-08cab6b963c7 format: uuid readOnly: true type: string is_pin_set: default: false description: indicates whether a pin has been set on the card example: true readOnly: true type: boolean last_four: description: The last 4 digits of the card PAN example: '1234' readOnly: true type: string last_modified_time: description: The timestamp representing when the card was last modified at example: '2010-05-06T12:23:34.321Z' format: date-time readOnly: true type: string metadata: $ref: '#/components/schemas/card_metadata' reissue_reason: description: > This is the reason the card needs to be reissued, if any. The reason determines several behaviours: - whether or not the new card will use the same PAN as the original card - the old card will be terminated and if so, when it will be terminated Reason | Same PAN | Terminate Old Card ---------------------- | -------- | ------------------ EXPIRATION | yes | on activation LOST | no | immediately STOLEN | no | immediately DAMAGED | yes | on activation VIRTUAL_TO_PHYSICAL(*) | yes | on activation PRODUCT_CHANGE | yes | on activation NAME_CHANGE(**) | yes | on activation APPEARANCE | yes | on activation (*) VIRTUAL_TO_PHYSICAL is deprecated. Please use PRODUCT_CHANGE whenever reissuing from one card product to another, including from a virtual product to a physical product. (**) NAME_CHANGE is deprecated. Please use APPEARANCE whenever reissuing in order to change the appearance of a card, such as the printed name or custom image. For all reasons, the new card will use the same PIN as the original card and digital wallet tokens will reassigned to the new card enum: - APPEARANCE - DAMAGED - EXPIRATION - LOST - NAME_CHANGE - PRODUCT_CHANGE - STOLEN - VIRTUAL_TO_PHYSICAL type: string reissued_from_id: description: > When reissuing a card, specify the card to be replaced here. When getting a card's details, if this card was issued as a reissuance of another card, this ID refers to the card was replaced. If this field is set, then reissue_reason must also be set. example: 7d943c51-e4ff-4e57-9558-08cab6b963c7 format: uuid type: string reissued_to_id: description: >- If this card was reissued, this ID refers to the card that replaced it. example: 7d943c51-e4ff-4e57-9558-08cab6b963c7 format: uuid readOnly: true type: string timestamp_pin_set: description: Time when the PIN was last set or changed. example: '2010-05-06T12:23:34.321Z' format: date-time readOnly: true type: string type: $ref: '#/components/schemas/card_type' required: - form type: object - $ref: '#/components/schemas/card_format' shipping: description: >- Details about the shipping method. If supplied this will override the default shipping address of the customer or account. properties: address: allOf: - $ref: '#/components/schemas/address1' description: >- The address to which the card will be shipped - Defaults to account shipping address if none supplied care_of_line: description: The name of the person to send in care of type: string is_expedited_fulfillment: default: false deprecated: true description: Is the shipment expedited type: boolean method: default: LOCAL_MAIL description: > The shipping method. * `INTERNATIONAL_GROUND` is only available for addresses in Canada and Mexico. enum: - INTERNATIONAL - INTERNATIONAL_GROUND - INTERNATIONAL_PRIORITY - LOCAL_MAIL - LOCAL_PRIORITY - OVERNIGHT - TWO_DAY example: LOCAL_MAIL type: string phone_number: description: The phone number of the recipient example: '+14374570680' pattern: ^\+[1-9]\d{1,14}$ type: string recipient_name: $ref: '#/components/schemas/recipient_name' type: object card_status_object: description: The status of the card properties: card_status: $ref: '#/components/schemas/card_status' memo: $ref: '#/components/schemas/card_status_reason_memo' pending_reasons: $ref: '#/components/schemas/card_status_pending_reasons' status_reason: $ref: '#/components/schemas/card_status_reason_code' required: - card_status title: Status type: object card_fulfillment_status: description: The status indicating the state of the card issuance enum: - DIGITALLY_PRESENTED - ISSUED - ORDERED - REISSUED - REJECTED - REORDERED - SHIPPED title: Card Fulfillment Status type: string fulfillment_details: properties: ship_date: description: >- The date that the card was shipped as reported by the card fulfillment provider example: '2022-07-19' format: date readOnly: true type: string shipping_method: description: >- The specific shipping method as reported by the card fulfillment provider example: UPS Next Day Air Saver readOnly: true type: string tracking_number: description: The shipment tracking number example: 1ZW3268W1319325382 readOnly: true type: string type: object emboss_name: description: >- The customer details to emboss on the card - Defaults to customer first and last name. Is limited to 21 characters. Valid characters are A-Z, a-z, 0-9, space ( ), period (.), comma (,), forward slash (/), hyphen (-), ampersand (&), single quote ('). properties: line_1: description: line 1 example: Jane Smith type: string line_2: description: line 2 example: Acme Inc. type: string required: - line_1 type: object card_metadata: additionalProperties: type: string description: Additional data to include in the request structured as key-value pairs type: object card_format: properties: form: description: PHYSICAL or VIRTUAL. enum: - PHYSICAL - VIRTUAL type: string required: - form type: object address1: properties: address_line_1: description: Street address line 1 example: 100 Main St. maxLength: 100 type: string address_line_2: description: Street address line 2 example: Suite 99 maxLength: 100 type: string city: description: City example: New York type: string country_code: description: ISO-3166-1 Alpha-2 country code example: US type: string postal_code: description: Postal code example: '49633' type: string state: description: State, region, province, or prefecture example: NY type: string required: - address_line_1 - city - country_code - postal_code - state type: object recipient_name: description: The name of the recipient to whom the card will be shipped properties: first_name: example: Jane maxLength: 30 type: string last_name: example: Smith maxLength: 30 type: string middle_name: example: Anne maxLength: 30 type: string required: - first_name - last_name type: object card_status_reason_memo: description: Additional details about the reason for the status change maxLength: 255 type: string card_status_pending_reasons: description: reasons why the card status is PENDING properties: is_waiting_for_bulk_shipment: description: > The card is to be shipping as part of a bulk shipment but that bulk shipment has not yet been released. type: boolean is_waiting_for_image: description: > The card has a custom image and either that image hasn't yet been uploaded and approved or the card has not yet been processed by the periodic daily custom card image processing task. type: boolean is_waiting_for_pin: description: > The card requires a PIN to be set before it can be issued (refer to the pin_issuance_policy of the related card product). The PIN has not yet been set and not enough time has passed to use a random PIN (if applicable). type: boolean type: object card_status_reason_code: description: | The reason for the card status Code | Description --- | --- NEW | Card activated REQ | Requested by you INA | Dormant UNK | Invalid shipping address NEG | Negative account balance REV | Account under review SUS | Suspicious activity OUT | Activity outside program parameters FRD | Confirmed fraud MAT | Matched with an OFAC list LOS | Card reported lost CLO | Card was cloned COM | Account or card was compromised TMP | Awaiting customer confirmation PRC | Initiated by Processor ISS | Initiated by Issuer EXP | Card expired KYC | Failed KYC INF | Information was validated ACT | Account activity was validated AUX | Initiated by a third party PIN | PIN try limit reached STO | Card reported stolen ADD | Address issue NAM | Name issue SSN | SSN issue DOB | DOB issue EML | Email issue PHO | Phone issue FUL | Account/fulfillment mismatch OTH | Other enum: - ACT - ADD - AUX - CLO - COM - DOB - EML - EXP - FRD - FUL - INA - INF - ISS - KYC - LOS - MAT - NAM - NEG - NEW - OTH - OUT - PHO - PIN - PRC - REQ - REV - SSN - STO - SUS - TMP - UNK type: string responses: bad_request: content: application/problem+json: schema: $ref: '#/components/schemas/error' description: BadRequest unauthorized: content: application/problem+json: schema: $ref: '#/components/schemas/error' description: Unauthorized forbidden: content: application/problem+json: schema: $ref: '#/components/schemas/error' description: Forbidden error unprocessable_entity: content: application/problem+json: schema: $ref: '#/components/schemas/error' description: Unprocessable entity request response internal_server_error: content: application/problem+json: schema: $ref: '#/components/schemas/error' description: Internal server error securitySchemes: bearerAuth: bearerFormat: api_key scheme: bearer type: http ````