Bulk Card Orders

Use the /bulkissuances endpoint to order physical payment cards in bulk. For more information on cards, card products, and bulk card ordering, see About Cards. Some attributes of the bulkissuance object can also be defined in an associated card or cardproduct object. If you define one of these attributes in more than one object, the Marqeta platform applies an order of precedence to determine which attribute to use at fulfillment time. The order of precedence is as follows:

card

bulkissuance

cardproduct

Defining an attribute in an object with higher precedence does not overwrite the same attribute in a lower-precedence object; the Marqeta platform ignores these lower-precedence attributes. For more information on cards, see About Cards.

Create bulk card order

Action: POST
Endpoint: /bulkissuances Use this endpoint to order physical cards in bulk. A new bulk card order creates new cards or users, generally within about a day. Before creating a bulk card order, set the config.fulfillment.bulk_ship field of the associated card product to true. To associate all cards with the same user:

Set user_association.single_inventory_user=true
Set user_association.single_inventory_user_token equal to the token of an existing user.

The bulk card order automatically populates the database with the specified card objects. Values for the card token fields are generated in the format card-numericPostfix, where numericPostfix is a randomly generated number that is added for each new card that is generated. To associate each card with a unique user: Set user_association.single_inventory_user=false. Both the cards and their associated users are automatically generated. Values for the user token fields are generated in the format user-numericPostfix. The numericPostfix values for cards and their associated users match. This value is also printed on the physical cards if the name_line_1_numeric_postfix field is set to true.

Request body

Fields	Description
card_allocation integer Required	Number of cards in the order. Allowable Values: 50000 max The actual number of cards processed per day depends on your fulfillment provider. Contact your Marqeta representative for more information.
card_product_token string Required	Specifies the card product from which to create your cards. Allowable Values: 1–36 chars Send a `GET` request to `/cardproducts` to retrieve card product tokens.
expedite boolean Optional	Set to `true` to request expedited processing of the order by your card fulfillment provider. This expedited service is available for cards fulfilled by Perfect Plastic Printing, IDEMIA, and Arroweye Solutions. NOTE: Contact your Marqeta representative for information regarding the cost of expedited service. Allowable Values: `true`, `false` Default value: `false`
expiration_offset object Optional	Specifies the length of time after the date of issue for which the cards are valid. Allowable Values: `unit`, `value`
expiration_offset.unit string Optional	Specifies the units for the `value` field in this object. Allowable Values: `YEARS`, `MONTHS`, `DAYS`, `HOURS`, `MINUTES`, `SECONDS` Default value: `YEARS`
expiration_offset.value integer Optional	Specifies the number of time units (as defined by the `unit` field in this object) for which the cards are valid. In other words, cards expire `value` x `unit` after the date of issue. This number is rounded as follows: - YEARS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 Jan 2021 and `value = 1`, the cards expire on the last day of Jan 2022. - MONTHS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 May 2022 and `value = 1`, the cards expire on the last day of June 2022. - DAYS – Rounds up to the last second of the day of expiration. - HOURS, MINUTES, SECONDS – No rounding. Allowable Values: Any positive integer Default value: 4
fulfillment object Required	Specifies certain physical characteristics of a card, as well as bulk shipment information. Allowable Values: `card_personalization`, `shipping`
fulfillment.card_personalization object Required	Specifies personalized attributes to be added to the card. Allowable Values: `carrier`, `images`, `perso_type`, `text`
fulfillment.card_personalization.carrier object Optional	Specifies attributes of the card carrier. Allowable Values: `logo_file`, `logo_thumbnail_file`, `message_file`, `message_line`, `template_id`
fulfillment.card_personalization.carrier.logo_file string Optional	Specifies an image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.carrier.logo_thumbnail_file string Optional	Specifies a thumbnail-sized rendering of the image specified in the `logo_file` field. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.carrier.message_file string Optional	Specifies a text file containing a custom message to print on the card carrier. Allowable Values: Contains the name of the text file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.carrier.message_line string Optional	Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max
fulfillment.card_personalization.carrier.template_id string Optional	Specifies the card carrier template to use. Allowable Values: Card carrier template ID
fulfillment.card_personalization.images object Optional	Specifies personalized images that appear on the card. Allowable Values: `card`, `carrier`, `carrier_return_window`, `signature`
fulfillment.card_personalization.images.card object Optional	Specifies personalized images that appear on the card. Allowable Values: `name`, `thermal_color`
fulfillment.card_personalization.images.card.name string Optional	Specifies a PNG image to display on the card. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.images.card.thermal_color string Optional	Specifies the color of the image displayed on the card. Allowable Values: Contains the name of the color and must match one of the provider’s predefined colors.
fulfillment.card_personalization.images.carrier object Optional	Specifies personalized images that appear on the card carrier. Allowable Values: `message_1`, `name`
fulfillment.card_personalization.images.carrier.message_1 string Optional	Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max
fulfillment.card_personalization.images.carrier.name string Optional	Specifies a PNG image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.images.carrier_return_window object Optional	Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: `name`
fulfillment.card_personalization.images.carrier_return_window.name string Optional	Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.images.signature object Optional	Specifies a PNG image of the cardholder’s signature. Allowable Values: `name`
fulfillment.card_personalization.images.signature.name string Optional	Specifies a PNG image of the cardholder’s signature. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.perso_type string Optional	Specifies the type of card personalization. Allowable Values: `EMBOSS`, `LASER`, `FLAT`
fulfillment.card_personalization.text object Required	Specifies personalized text that appears on the card. Allowable Values: `name_line_1`, `name_line_2`, `name_line_3`
fulfillment.card_personalization.text.name_line_1 object Required	Specifies the first line of personalized text that appears on the card. Allowable Values: `name_line_1.value` 21 char max; if `name_line_1_numeric_postfix` is `true`, 14 char max. Strings longer than the character limit are truncated.
fulfillment.card_personalization.text.name_line_1.value string Optional	Line of personalized text printed on the card. Allowable Values: 21 char max
fulfillment.card_personalization.text.name_line_2 object Optional	Specifies the second line of personalized text that appears on the card. Allowable Values: `name_line_2.value`
fulfillment.card_personalization.text.name_line_2.value string Optional	Line of personalized text printed on the card. Allowable Values: 21 char max
fulfillment.card_personalization.text.name_line_3 object Optional	Specifies the third line of personalized text that appears on the card. Allowable Values: `name_line_3.value`
fulfillment.card_personalization.text.name_line_3.value string Optional	Line of personalized text printed on the card. Allowable Values: 21 char max
fulfillment.shipping object Optional	Specifies shipping details for the order. Allowable Values: `care_of_line`, `method`, `recipient_address`, `return_address`
fulfillment.shipping.care_of_line string Optional	Adds the specified value as a care of (C/O) line to the mailing carrier. NOTE: This field can be specified on cards, card products, and bulk card orders. If you specify this field at multiple levels, the order of precedence is: card, bulk card order, card product. Allowable Values: 255 char max
fulfillment.shipping.method string Optional	Specifies the shipping service. Allowable Values: `LOCAL_MAIL`, `LOCAL_MAIL_PACKAGE`, `GROUND`, `TWO_DAY`, `OVERNIGHT`, `INTERNATIONAL`, `INTERNATIONAL_PRIORITY`, `LOCAL_PRIORITY`, `FEDEX_EXPEDITED`, `FEDEX_REGULAR`, `UPS_EXPEDITED`, `UPS_REGULAR`, `USPS_EXPEDITED`, `USPS_REGULAR` Shipping options vary by card provider. For details on the specific shipping companies and services offered by your card provider, contact your Marqeta representative.
fulfillment.shipping.recipient_address object Optional	Address to which the order will be shipped. In order to generate cards, a valid shipping address must be provided by one of these: - The card or bulk card order’s `fulfillment.shipping.recipient_address` field - The users’ `address` fields - The card product’s `config.fulfillment.shipping.recipient_address` field The order of precedence from highest to lowest is card, user, card product. To be valid, an address must have the `address1`, `city`, `state`, and `postal_code` or `zip` fields populated. The `country` field defaults to USA if unpopulated. Allowable Values: Valid `recipient_address` object
fulfillment.shipping.recipient_address.address1 string Optional	Number and street of the address. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
fulfillment.shipping.recipient_address.address2 string Optional	Additional address information. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
fulfillment.shipping.recipient_address.city string Optional	City of the address. Allowable Values: 40 char max
fulfillment.shipping.recipient_address.country string Optional	Country of the address. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name “Spain”. The ISO maintains the full list of country codes.
fulfillment.shipping.recipient_address.first_name string Optional	First name of the addressee. Allowable Values: 40 char max
fulfillment.shipping.recipient_address.last_name string Optional	Last name of the addressee. Allowable Values: 40 char max
fulfillment.shipping.recipient_address.middle_name string Optional	Middle name of the addressee. Allowable Values: 40 char max
fulfillment.shipping.recipient_address.phone string Optional	Telephone number of the addressee. Allowable Values: 20 char max
fulfillment.shipping.recipient_address.postal_code string Optional	Postal code of the address. Allowable Values: 10 char max
fulfillment.shipping.recipient_address.state string Optional	State of the address. Allowable Values: 32 char max
fulfillment.shipping.recipient_address.zip string Optional	United States ZIP code of the address. Allowable Values: 10 char max
fulfillment.shipping.return_address object Optional	Address to which the order will be returned if shipping fails. Allowable Values: `address1`, `address2`, `city`, `country`, `first_name`, `last_name`, `middle_name`, `phone`, `postal_code`, `state`, `zip`
fulfillment.shipping.return_address.address1 string Optional	Number and street of the address. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
fulfillment.shipping.return_address.address2 string Optional	Additional address information. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
fulfillment.shipping.return_address.city string Optional	City of the address. Allowable Values: 40 char max
fulfillment.shipping.return_address.country string Optional	Country of the address. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name “Spain”. The ISO maintains the full list of country codes.
fulfillment.shipping.return_address.first_name string Optional	First name of the addressee. Allowable Values: 40 char max
fulfillment.shipping.return_address.last_name string Optional	Last name of the addressee. Allowable Values: 40 char max
fulfillment.shipping.return_address.middle_name string Optional	Middle name of the addressee. Allowable Values: 40 char max
fulfillment.shipping.return_address.phone string Optional	Telephone number of the addressee. Allowable Values: 20 char max
fulfillment.shipping.return_address.postal_code string Optional	Postal code of the address. Allowable Values: 10 char max
fulfillment.shipping.return_address.state string Optional	State of the address. Allowable Values: 32 char max
fulfillment.shipping.return_address.zip string Optional	United States ZIP code of the address. Allowable Values: 10 char max
name_line_1_numeric_postfix boolean Optional	If set to `true`, the unique numeric postfix appended to each card’s token field is also appended to the card’s `fulfillment.card_personalization.text.name_line_1.value` field. Allowable Values: `true`, `false` Default value: `false`
name_line_1_random_postfix boolean Optional	If set to `true`, the unique random postfix appended to each card’s token field is also appended to the card’s `fulfillment.card_personalization.text.name_line_1.value` field. Allowable Values: `true`, `false` Default value: `false`
token string Required	If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 1–36 chars
user_association object Optional	Associates each card with a user. Allowable Values: `single_inventory_user`, `single_inventory_user_token`
user_association.single_inventory_user boolean Optional	Set to `true` to associate all cards with the same user. Set to `false` to associate each card with a different user. When set to `false`, users are generated automatically and associated with the cards. Allowable Values: `true`, `false` Default value: `false`
user_association.single_inventory_user_token string Optional	If `single_inventory_user=true`, use this field to specify the token of an existing user. All cards in the order will be associated with this user. Allowable Values: 1–36 chars

Sample request body

JSON

{
  "token": "bulk_06_token",
  "card_product_token": "my_card_product_02",
  "card_allocation": 3,
  "user_association": {
    "single_inventory_user": false
  },
  "name_line_1_numeric_postfix": true,
  "fulfillment": {
    "shipping": {
      "method": "UPS_REGULAR",
      "return_address": {
        "address1": "1222 Blake Street",
        "city": "Berkeley",
        "state": "CA",
        "postal_code": "94702",
        "country": "USA",
        "phone": "5102222222",
        "first_name": "Shipping",
        "last_name": "R_US"
      },
      "recipient_address": {
        "address1": "1255 Lake Street",
        "city": "Oakland",
        "state": "CA",
        "postal_code": "94611",
        "country": "USA",
        "phone": "5103333333",
        "first_name": "Saki",
        "last_name": "Dogger"
      }
    },
    "card_personalization": {
      "text": {
        "name_line_1": {
          "value": "Saki Dogger"
        },
        "name_line_2": {
          "value": "Aegis Fleet Services"
        }
      },
      "carrier": {
        "name": "my_carrier_logo.png",
        "message_line": "my message"
      },
      "images": {
        "card": {
          "name": "my_card_logo.png",
          "thermal_color": "Black"
        },
        "signature": {
          "name": "my_signature.png"
        },
        "carrier_return_window": {
          "name": "my_return_address_image.png"
        }
      }
    }
  }
}

Response body

Fields	Description
card_allocation integer Returned	Number of cards in the order. Allowable Values: 50000 max
card_fulfillment_time datetime Conditionally returned	Date and time when the bulk card order was fulfilled, in UTC. This field is included if your bulk card order has been processed. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
card_product_token string Returned	Specifies the card product from which the cards are created. Allowable Values: 1–36 chars
cards_processed integer Conditionally returned	Number of cards processed in the bulk card order. This field is returned if it exists in the resource. Allowable Values: Any positive integer
created_time datetime Conditionally returned	Date and time when the resource was created, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
expedite boolean Conditionally returned	Indicates if expedited processing of this bulk card order was requested. This field is returned if it exists in the resource. Allowable Values: `true`, `false`
expiration_offset object Conditionally returned	Specifies the length of time after the date of issue for which the cards are valid. Allowable Values: `unit`, `value`
expiration_offset.unit string Conditionally returned	Specifies the units for the `value` field in this object. Allowable Values: `YEARS`, `MONTHS`, `DAYS`, `HOURS`, `MINUTES`, `SECONDS` Default value: `YEARS`
expiration_offset.value integer Conditionally returned	Specifies the number of time units (as defined by the `unit` field in this object) for which the cards are valid. In other words, cards expire `value` x `unit` after the date of issue. This number is rounded as follows: - YEARS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 Jan 2021 and `value = 1`, the cards expire on the last day of Jan 2022. - MONTHS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 May 2022 and `value = 1`, the cards expire on the last day of June 2022. - DAYS – Rounds up to the last second of the day of expiration. - HOURS, MINUTES, SECONDS – No rounding. Allowable Values: Any positive integer Default value: 4
fulfillment object Returned	Specifies certain physical characteristics of a card, as well as bulk shipment information. This object is returned if it exists in the resource. Allowable Values: `card_personalization`, `shipping`
fulfillment.card_personalization object Returned	Specifies personalized attributes to be added to the card. Allowable Values: `carrier`, `images`, `perso_type`, `text`
fulfillment.card_personalization.carrier object Conditionally returned	Specifies attributes of the card carrier. Allowable Values: `logo_file`, `logo_thumbnail_file`, `message_file`, `message_line`, `template_id`
fulfillment.card_personalization.carrier.logo_file string Conditionally returned	Specifies an image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.carrier.logo_thumbnail_file string Conditionally returned	Specifies a thumbnail-sized rendering of the image specified in the `logo_file` field. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.carrier.message_file string Conditionally returned	Specifies a text file containing a custom message to print on the card carrier. Allowable Values: Contains the name of the text file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.carrier.message_line string Conditionally returned	Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max
fulfillment.card_personalization.carrier.template_id string Conditionally returned	Specifies the card carrier template to use. Allowable Values: Card carrier template ID
fulfillment.card_personalization.images object Conditionally returned	Specifies personalized images that appear on the card. Allowable Values: `card`, `carrier`, `carrier_return_window`, `signature`
fulfillment.card_personalization.images.card object Conditionally returned	Specifies personalized images that appear on the card. Allowable Values: `name`, `thermal_color`
fulfillment.card_personalization.images.card.name string Conditionally returned	Specifies a PNG image to display on the card. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.images.card.thermal_color string Conditionally returned	Specifies the color of the image displayed on the card. Allowable Values: Contains the name of the color and must match one of the provider’s predefined colors.
fulfillment.card_personalization.images.carrier object Conditionally returned	Specifies personalized images that appear on the card carrier. Allowable Values: `message_1`, `name`
fulfillment.card_personalization.images.carrier.message_1 string Conditionally returned	Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max
fulfillment.card_personalization.images.carrier.name string Conditionally returned	Specifies a PNG image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.images.carrier_return_window object Conditionally returned	Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: `name`
fulfillment.card_personalization.images.carrier_return_window.name string Conditionally returned	Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.images.signature object Conditionally returned	Specifies a PNG image of the cardholder’s signature. Allowable Values: `name`
fulfillment.card_personalization.images.signature.name string Conditionally returned	Specifies a PNG image of the cardholder’s signature. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.perso_type string Conditionally returned	Specifies the type of card personalization. Allowable Values: `EMBOSS`, `LASER`, `FLAT`
fulfillment.card_personalization.text object Returned	Specifies personalized text that appears on the card. Allowable Values: `name_line_1`, `name_line_2`, `name_line_3`
fulfillment.card_personalization.text.name_line_1 object Returned	Specifies the first line of personalized text that appears on the card. Allowable Values: `name_line_1.value` 21 char max; if `name_line_1_numeric_postfix` is `true`, 14 char max. Strings longer than the character limit are truncated.
fulfillment.card_personalization.text.name_line_1.value string Conditionally returned	Line of personalized text printed on the card. Allowable Values: 21 char max
fulfillment.card_personalization.text.name_line_2 object Conditionally returned	Specifies the second line of personalized text that appears on the card. Allowable Values: `name_line_2.value`
fulfillment.card_personalization.text.name_line_2.value string Conditionally returned	Line of personalized text printed on the card. Allowable Values: 21 char max
fulfillment.card_personalization.text.name_line_3 object Conditionally returned	Specifies the third line of personalized text that appears on the card. Allowable Values: `name_line_3.value`
fulfillment.card_personalization.text.name_line_3.value string Conditionally returned	Line of personalized text printed on the card. Allowable Values: 21 char max
fulfillment.shipping object Conditionally returned	Specifies shipping details for the order. This object is returned if it exists in the resource. Allowable Values: `care_of_line`, `method`, `recipient_address`, `return_address`
fulfillment.shipping.care_of_line string Conditionally returned	Specifies the value of the care of (C/O) line on the mailing carrier. This field is returned if it exists in the resource. Allowable Values: 255 char max
fulfillment.shipping.method string Conditionally returned	Specifies the shipping service. This field is returned if it exists in the resource. Allowable Values: `LOCAL_MAIL`, `LOCAL_MAIL_PACKAGE`, `GROUND`, `TWO_DAY`, `OVERNIGHT`, `INTERNATIONAL`, `INTERNATIONAL_PRIORITY`, `LOCAL_PRIORITY`, `FEDEX_EXPEDITED`, `FEDEX_REGULAR`, `UPS_EXPEDITED`, `UPS_REGULAR`, `USPS_EXPEDITED`, `USPS_REGULAR`
fulfillment.shipping.recipient_address object Conditionally returned	Address to which the order will be shipped. This field is returned if it exists in the resource. Allowable Values: Existing `recipient_address` object
fulfillment.shipping.recipient_address.address1 string Conditionally returned	Number and street of the address. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
fulfillment.shipping.recipient_address.address2 string Conditionally returned	Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
fulfillment.shipping.recipient_address.city string Conditionally returned	City of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max
fulfillment.shipping.recipient_address.country string Conditionally returned	Country of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name “Spain”. The ISO maintains the full list of country codes.
fulfillment.shipping.recipient_address.first_name string Conditionally returned	First name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max
fulfillment.shipping.recipient_address.last_name string Conditionally returned	Last name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max
fulfillment.shipping.recipient_address.middle_name string Conditionally returned	Middle name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max
fulfillment.shipping.recipient_address.phone string Conditionally returned	Telephone number of the addressee. This field is returned if it exists in the resource. Allowable Values: 20 char max
fulfillment.shipping.recipient_address.postal_code string Conditionally returned	Postal code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max
fulfillment.shipping.recipient_address.state string Conditionally returned	State or province of the address. This field is returned if it exists in the resource. Allowable Values: 32 char max
fulfillment.shipping.recipient_address.zip string Conditionally returned	United States ZIP code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max
fulfillment.shipping.return_address object Conditionally returned	Address to which the order will be returned if shipping fails. This object is returned if it exists in the resource. Allowable Values: Existing `return_address` object
fulfillment.shipping.return_address.address1 string Conditionally returned	Number and street of the address. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
fulfillment.shipping.return_address.address2 string Conditionally returned	Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
fulfillment.shipping.return_address.city string Conditionally returned	City of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max
fulfillment.shipping.return_address.country string Conditionally returned	Country of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name “Spain”. The ISO maintains the full list of country codes.
fulfillment.shipping.return_address.first_name string Conditionally returned	First name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max
fulfillment.shipping.return_address.last_name string Conditionally returned	Last name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max
fulfillment.shipping.return_address.middle_name string Conditionally returned	Middle name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max
fulfillment.shipping.return_address.phone string Conditionally returned	Telephone number of the addressee. This field is returned if it exists in the resource. Allowable Values: 20 char max
fulfillment.shipping.return_address.postal_code string Conditionally returned	Postal code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max
fulfillment.shipping.return_address.state string Conditionally returned	State or province of the address. This field is returned if it exists in the resource. Allowable Values: 32 char max
fulfillment.shipping.return_address.zip string Conditionally returned	United States ZIP code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max
name_line1_end_index integer Conditionally returned	This field is included if your bulk card order has been processed. You can use the `name_line1_start_index` and `name_line1_end_index` fields to identify the cards and users associated with the order. For example, if the start index is “1” and the end index is “3”, the card tokens are “card-1”, “card-2”, and “card-3”, and the user tokens are “user-1”, “user-2”, and “user-3”. See Create bulk card order for more information about the automatic generation and naming of cards and users. Allowable Values: Any positive integer
name_line1_start_index integer Conditionally returned	This field is included if your bulk card order has been processed. You can use the `name_line1_start_index` and `name_line1_end_index` fields to identify the cards and users associated with the order. For example, if the start index is “1” and the end index is “3”, the card tokens are “card-1”, “card-2”, and “card-3”, and the user tokens are “user-1”, “user-2”, and “user-3”. See Create bulk card order for more information about the automatic generation and naming of cards and users. Allowable Values: Any positive integer
name_line_1_numeric_postfix boolean Conditionally returned	If set to `true`, the unique numeric postfix appended to each card’s token field is also appended to the card’s `fulfillment.card_personalization.text.name_line_1.value` field. Allowable Values: `true`, `false`
name_line_1_random_postfix boolean Conditionally returned	If set to `true`, the unique random postfix appended to each card’s token field is also appended to the card’s `fulfillment.card_personalization.text.name_line_1.value` field. This field is returned if it exists in the resource. Allowable Values: `true`, `false`
provider_ship_date datetime Conditionally returned	Date and time when the card provider shipped the bulk card order, in UTC. This field is included if your bulk card order has shipped. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
provider_shipping_method string Conditionally returned	Shipping method used by the card provider. `United_Postal_Service`, for example. This field is included if your bulk card order has shipped. Allowable Values: String
provider_tracking_number string Conditionally returned	A tracking number is included only if your card provider is Arroweye Solutions. This field is included if your bulk card order has shipped. Allowable Values: String
token string Returned	Unique identifier of the bulk card order. Allowable Values: 1–36 chars
user_association object Conditionally returned	Associates each card with a user. Allowable Values: `single_inventory_user`, `single_inventory_user_token`
user_association.single_inventory_user boolean Conditionally returned	Set to `true` to associate all cards with the same user. Set to `false` to associate each card with a different user. When set to `false`, users are generated automatically and associated with the cards. Allowable Values: `true`, `false` Default value: `false`
user_association.single_inventory_user_token string Conditionally returned	If `single_inventory_user=true`, use this field to specify the token of an existing user. All cards in the order will be associated with this user. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "token": "bulk_06_token",
  "expedite": false,
  "fulfillment": {
    "shipping": {
      "method": "UPS_REGULAR",
      "return_address": {
        "first_name": "Shipping",
        "last_name": "R_US",
        "address1": "1222 Blake Street",
        "city": "Berkeley",
        "state": "CA",
        "postal_code": "94702",
        "country": "USA",
        "phone": "5102222222"
      },
      "recipient_address": {
        "first_name": "Saki",
        "last_name": "Dogger",
        "address1": "1255 Lake Street",
        "city": "Oakland",
        "state": "CA",
        "postal_code": "94611",
        "country": "USA",
        "phone": "5103333333"
      }
    },
    "card_personalization": {
      "text": {
        "name_line_1": {
          "value": "Saki Dogger"
        },
        "name_line_2": {
          "value": "Aegis Fleet Services"
        }
      },
      "carrier": {
        "name": "my_carrier_logo.png",
        "message_line": "my message"
      },
      "images": {
        "card": {
          "name": "my_card_logo.png",
          "thermal_color": "Black"
        }
      },
      "signature": {
        "name": "my_signature.png"
      },
      "carrier_return_window": {
        "name": "my_return_address_image.png"
      }
    }
  },
  "card_product_token": "my_card_product_02",
  "card_allocation": 3,
  "user_association": {
    "single_inventory_user": false,
    "name_line_1_numeric_postfix": true,
    "expiration_offset": {
      "unit": "YEARS",
      "value": 10
    }
  },
  "created_time": "2022-08-06T00:06:34Z",
  "api": "bulkissuances",
  "endpoint": "/bulkissuances",
  "method": "post",
  "cp_id": 1,
  "bc_id": 1
}

List bulk card orders

Action: GET
Endpoint: /bulkissuances Use this endpoint to list existing bulk card orders. This endpoint supports pagination and sorting.

URL query parameters

Fields	Description
count integer Optional	Number of bulk card orders to retrieve. Allowable Values: 1-10 Default value: 5
start_index integer Optional	Sort order index of the first resource in the returned array. Allowable Values: Any integer Default value: 0 (The first bulk card order resource in your system)
sort_by string Optional	Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order. Allowable Values: `createdTime`, `lastModifiedTime`, or any field in the resource model Default value: `-createdTime`

Response body

Fields	Description
count integer Conditionally returned	Number of resources retrieved. This field is returned if there are resources in your returned array. Allowable Values: 1-10
data array of objects Conditionally returned	Array of bulk issuance objects. Objects are returned as appropriate to your query. Allowable Values: Valid array of one or more bulk issuance objects
data[].card_allocation integer Returned	Number of cards in the order. Allowable Values: 50000 max
data[].card_fulfillment_time datetime Conditionally returned	Date and time when the bulk card order was fulfilled, in UTC. This field is included if your bulk card order has been processed. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
data[].card_product_token string Returned	Specifies the card product from which the cards are created. Allowable Values: 1–36 chars
data[].cards_processed integer Conditionally returned	Number of cards processed in the bulk card order. This field is returned if it exists in the resource. Allowable Values: Any positive integer
data[].created_time datetime Conditionally returned	Date and time when the resource was created, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
data[].expedite boolean Conditionally returned	Indicates if expedited processing of this bulk card order was requested. This field is returned if it exists in the resource. Allowable Values: `true`, `false`
data[].expiration_offset object Conditionally returned	Specifies the length of time after the date of issue for which the cards are valid. Allowable Values: `unit`, `value`
data[].expiration_offset.unit string Conditionally returned	Specifies the units for the `value` field in this object. Allowable Values: `YEARS`, `MONTHS`, `DAYS`, `HOURS`, `MINUTES`, `SECONDS` Default value: `YEARS`
data[].expiration_offset.value integer Conditionally returned	Specifies the number of time units (as defined by the `unit` field in this object) for which the cards are valid. In other words, cards expire `value` x `unit` after the date of issue. This number is rounded as follows: - YEARS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 Jan 2021 and `value = 1`, the cards expire on the last day of Jan 2022. - MONTHS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 May 2022 and `value = 1`, the cards expire on the last day of June 2022. - DAYS – Rounds up to the last second of the day of expiration. - HOURS, MINUTES, SECONDS – No rounding. Allowable Values: Any positive integer Default value: 4
data[].fulfillment object Returned	Specifies certain physical characteristics of a card, as well as bulk shipment information. This object is returned if it exists in the resource. Allowable Values: `card_personalization`, `shipping`
data[].fulfillment.card_personalization object Returned	Specifies personalized attributes to be added to the card. Allowable Values: `carrier`, `images`, `perso_type`, `text`
data[].fulfillment.card_personalization.carrier object Conditionally returned	Specifies attributes of the card carrier. Allowable Values: `logo_file`, `logo_thumbnail_file`, `message_file`, `message_line`, `template_id`
data[].fulfillment.card_personalization.carrier.logo_file string Conditionally returned	Specifies an image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
data[].fulfillment.card_personalization.carrier.logo_thumbnail_file string Conditionally returned	Specifies a thumbnail-sized rendering of the image specified in the `logo_file` field. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
data[].fulfillment.card_personalization.carrier.message_file string Conditionally returned	Specifies a text file containing a custom message to print on the card carrier. Allowable Values: Contains the name of the text file and must match the name of the file you send to your fulfillment provider.
data[].fulfillment.card_personalization.carrier.message_line string Conditionally returned	Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max
data[].fulfillment.card_personalization.carrier.template_id string Conditionally returned	Specifies the card carrier template to use. Allowable Values: Card carrier template ID
data[].fulfillment.card_personalization.images object Conditionally returned	Specifies personalized images that appear on the card. Allowable Values: `card`, `carrier`, `carrier_return_window`, `signature`
data[].fulfillment.card_personalization.images.card object Conditionally returned	Specifies personalized images that appear on the card. Allowable Values: `name`, `thermal_color`
data[].fulfillment.card_personalization.images.card.name string Conditionally returned	Specifies a PNG image to display on the card. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
data[].fulfillment.card_personalization.images.card.thermal_color string Conditionally returned	Specifies the color of the image displayed on the card. Allowable Values: Contains the name of the color and must match one of the provider’s predefined colors.
data[].fulfillment.card_personalization.images.carrier object Conditionally returned	Specifies personalized images that appear on the card carrier. Allowable Values: `message_1`, `name`
data[].fulfillment.card_personalization.images.carrier.message_1 string Conditionally returned	Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max
data[].fulfillment.card_personalization.images.carrier.name string Conditionally returned	Specifies a PNG image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
data[].fulfillment.card_personalization.images.carrier_return_window object Conditionally returned	Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: `name`
data[].fulfillment.card_personalization.images.carrier_return_window.name string Conditionally returned	Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
data[].fulfillment.card_personalization.images.signature object Conditionally returned	Specifies a PNG image of the cardholder’s signature. Allowable Values: `name`
data[].fulfillment.card_personalization.images.signature.name string Conditionally returned	Specifies a PNG image of the cardholder’s signature. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
data[].fulfillment.card_personalization.perso_type string Conditionally returned	Specifies the type of card personalization. Allowable Values: `EMBOSS`, `LASER`, `FLAT`
data[].fulfillment.card_personalization.text object Returned	Specifies personalized text that appears on the card. Allowable Values: `name_line_1`, `name_line_2`, `name_line_3`
data[].fulfillment.card_personalization.text.name_line_1 object Returned	Specifies the first line of personalized text that appears on the card. Allowable Values: `name_line_1.value` 21 char max; if `name_line_1_numeric_postfix` is `true`, 14 char max. Strings longer than the character limit are truncated.
data[].fulfillment.card_personalization.text.name_line_1.value string Conditionally returned	Line of personalized text printed on the card. Allowable Values: 21 char max
data[].fulfillment.card_personalization.text.name_line_2 object Conditionally returned	Specifies the second line of personalized text that appears on the card. Allowable Values: `name_line_2.value`
data[].fulfillment.card_personalization.text.name_line_2.value string Conditionally returned	Line of personalized text printed on the card. Allowable Values: 21 char max
data[].fulfillment.card_personalization.text.name_line_3 object Conditionally returned	Specifies the third line of personalized text that appears on the card. Allowable Values: `name_line_3.value`
data[].fulfillment.card_personalization.text.name_line_3.value string Conditionally returned	Line of personalized text printed on the card. Allowable Values: 21 char max
data[].fulfillment.shipping object Conditionally returned	Specifies shipping details for the order. This object is returned if it exists in the resource. Allowable Values: `care_of_line`, `method`, `recipient_address`, `return_address`
data[].fulfillment.shipping.care_of_line string Conditionally returned	Specifies the value of the care of (C/O) line on the mailing carrier. This field is returned if it exists in the resource. Allowable Values: 255 char max
data[].fulfillment.shipping.method string Conditionally returned	Specifies the shipping service. This field is returned if it exists in the resource. Allowable Values: `LOCAL_MAIL`, `LOCAL_MAIL_PACKAGE`, `GROUND`, `TWO_DAY`, `OVERNIGHT`, `INTERNATIONAL`, `INTERNATIONAL_PRIORITY`, `LOCAL_PRIORITY`, `FEDEX_EXPEDITED`, `FEDEX_REGULAR`, `UPS_EXPEDITED`, `UPS_REGULAR`, `USPS_EXPEDITED`, `USPS_REGULAR`
data[].fulfillment.shipping.recipient_address object Conditionally returned	Address to which the order will be shipped. This field is returned if it exists in the resource. Allowable Values: Existing `recipient_address` object
data[].fulfillment.shipping.recipient_address.address1 string Conditionally returned	Number and street of the address. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
data[].fulfillment.shipping.recipient_address.address2 string Conditionally returned	Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
data[].fulfillment.shipping.recipient_address.city string Conditionally returned	City of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max
data[].fulfillment.shipping.recipient_address.country string Conditionally returned	Country of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name “Spain”. The ISO maintains the full list of country codes.
data[].fulfillment.shipping.recipient_address.first_name string Conditionally returned	First name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max
data[].fulfillment.shipping.recipient_address.last_name string Conditionally returned	Last name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max
data[].fulfillment.shipping.recipient_address.middle_name string Conditionally returned	Middle name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max
data[].fulfillment.shipping.recipient_address.phone string Conditionally returned	Telephone number of the addressee. This field is returned if it exists in the resource. Allowable Values: 20 char max
data[].fulfillment.shipping.recipient_address.postal_code string Conditionally returned	Postal code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max
data[].fulfillment.shipping.recipient_address.state string Conditionally returned	State or province of the address. This field is returned if it exists in the resource. Allowable Values: 32 char max
data[].fulfillment.shipping.recipient_address.zip string Conditionally returned	United States ZIP code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max
data[].fulfillment.shipping.return_address object Conditionally returned	Address to which the order will be returned if shipping fails. This object is returned if it exists in the resource. Allowable Values: Existing `return_address` object
data[].fulfillment.shipping.return_address.address1 string Conditionally returned	Number and street of the address. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
data[].fulfillment.shipping.return_address.address2 string Conditionally returned	Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
data[].fulfillment.shipping.return_address.city string Conditionally returned	City of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max
data[].fulfillment.shipping.return_address.country string Conditionally returned	Country of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name “Spain”. The ISO maintains the full list of country codes.
data[].fulfillment.shipping.return_address.first_name string Conditionally returned	First name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max
data[].fulfillment.shipping.return_address.last_name string Conditionally returned	Last name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max
data[].fulfillment.shipping.return_address.middle_name string Conditionally returned	Middle name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max
data[].fulfillment.shipping.return_address.phone string Conditionally returned	Telephone number of the addressee. This field is returned if it exists in the resource. Allowable Values: 20 char max
data[].fulfillment.shipping.return_address.postal_code string Conditionally returned	Postal code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max
data[].fulfillment.shipping.return_address.state string Conditionally returned	State or province of the address. This field is returned if it exists in the resource. Allowable Values: 32 char max
data[].fulfillment.shipping.return_address.zip string Conditionally returned	United States ZIP code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max
data[].name_line1_end_index integer Conditionally returned	This field is included if your bulk card order has been processed. You can use the `name_line1_start_index` and `name_line1_end_index` fields to identify the cards and users associated with the order. For example, if the start index is “1” and the end index is “3”, the card tokens are “card-1”, “card-2”, and “card-3”, and the user tokens are “user-1”, “user-2”, and “user-3”. See Create bulk card order for more information about the automatic generation and naming of cards and users. Allowable Values: Any positive integer
data[].name_line1_start_index integer Conditionally returned	This field is included if your bulk card order has been processed. You can use the `name_line1_start_index` and `name_line1_end_index` fields to identify the cards and users associated with the order. For example, if the start index is “1” and the end index is “3”, the card tokens are “card-1”, “card-2”, and “card-3”, and the user tokens are “user-1”, “user-2”, and “user-3”. See Create bulk card order for more information about the automatic generation and naming of cards and users. Allowable Values: Any positive integer
data[].name_line_1_numeric_postfix boolean Conditionally returned	If set to `true`, the unique numeric postfix appended to each card’s token field is also appended to the card’s `fulfillment.card_personalization.text.name_line_1.value` field. Allowable Values: `true`, `false`
data[].name_line_1_random_postfix boolean Conditionally returned	If set to `true`, the unique random postfix appended to each card’s token field is also appended to the card’s `fulfillment.card_personalization.text.name_line_1.value` field. This field is returned if it exists in the resource. Allowable Values: `true`, `false`
data[].provider_ship_date datetime Conditionally returned	Date and time when the card provider shipped the bulk card order, in UTC. This field is included if your bulk card order has shipped. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
data[].provider_shipping_method string Conditionally returned	Shipping method used by the card provider. `United_Postal_Service`, for example. This field is included if your bulk card order has shipped. Allowable Values: String
data[].provider_tracking_number string Conditionally returned	A tracking number is included only if your card provider is Arroweye Solutions. This field is included if your bulk card order has shipped. Allowable Values: String
data[].token string Returned	Unique identifier of the bulk card order. Allowable Values: 1–36 chars
data[].user_association object Conditionally returned	Associates each card with a user. Allowable Values: `single_inventory_user`, `single_inventory_user_token`
data[].user_association.single_inventory_user boolean Conditionally returned	Set to `true` to associate all cards with the same user. Set to `false` to associate each card with a different user. When set to `false`, users are generated automatically and associated with the cards. Allowable Values: `true`, `false` Default value: `false`
data[].user_association.single_inventory_user_token string Conditionally returned	If `single_inventory_user=true`, use this field to specify the token of an existing user. All cards in the order will be associated with this user. Allowable Values: 1–36 chars
end_index integer Conditionally returned	Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer
is_more boolean Conditionally returned	A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist. This field is returned if there are resources in your returned array. Allowable Values: `true`, `false`
start_index integer Conditionally returned	Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer

Sample response body

JSON

{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": true,
  "data[]": {
    "token": "bulk_06_token",
    "expedite": false,
    "fulfillment": {
      "shipping": {
        "method": "UPS_REGULAR",
        "return_address": {
          "first_name": "Shipping",
          "last_name": "R_US",
          "address1": "1222 Blake Street",
          "city": "Berkeley",
          "state": "CA",
          "postal_code": "94702",
          "country": "USA",
          "phone": "5102222222"
        },
        "recipient_address": {
          "first_name": "Saki",
          "last_name": "Dogger",
          "address1": "1255 Lake Street",
          "city": "Oakland",
          "state": "CA",
          "postal_code": "94611",
          "country": "USA",
          "phone": "5103333333"
        },
        "card_personalization": {
          "text": {
            "name_line_1": {
              "value": "Saki Dogger"
            },
            "name_line_2": {
              "value": "Aegis Fleet Services"
            }
          },
          "carrier": {
            "name": "my_carrier_logo.png",
            "message_line": "my message"
          },
          "images": {
            "card": {
              "name": "my_card_logo.png",
              "thermal_color": "Black"
            },
            "signature": {
              "name": "my_signature.png"
            },
            "carrier_return_window": {
              "name": "my_return_address_image.png"
            }
          }
        },
        "card_product_token": "my_card_product_02",
        "card_allocation": 3,
        "user_association": {
          "single_inventory_user": false
        },
        "name_line_1_numeric_postfix": true,
        "expiration_offset": {
          "unit": "YEARS",
          "value": 10
        },
        "created_time": "2020-08-06T00:06:34Z",
        "name_line1_start_index": 1,
        "name_line1_end_index": 3,
        "card_fulfillment_time": "2022-08-07T23:59:44Z",
        "provider_ship_date": "2022-08-08T00:00:00Z",
        "provider_shipping_method": "United_Parcel_Service",
        "provider_tracking_number": "982247"
      }
    },
    "api": "bulkissuances",
    "endpoint": "/bulkissuances",
    "method": "get",
    "cp_id": 1,
    "bc_id": 1
  }
}

Retrieve bulk card order

Action: GET
Endpoint: /bulkissuances/{token} Use this endpoint to retrieve a specific bulk card order.

URL path parameters

Fields	Description
token string Required	The unique identifier of the bulk card order to retrieve. Allowable Values: Existing bulk card order token

Response body

Fields	Description
card_allocation integer Returned	Number of cards in the order. Allowable Values: 50000 max
card_fulfillment_time datetime Conditionally returned	Date and time when the bulk card order was fulfilled, in UTC. This field is included if your bulk card order has been processed. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
card_product_token string Returned	Specifies the card product from which the cards are created. Allowable Values: 1–36 chars
cards_processed integer Conditionally returned	Number of cards processed in the bulk card order. This field is returned if it exists in the resource. Allowable Values: Any positive integer
created_time datetime Conditionally returned	Date and time when the resource was created, in UTC. This field is returned if it exists in the resource. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
expedite boolean Conditionally returned	Indicates if expedited processing of this bulk card order was requested. This field is returned if it exists in the resource. Allowable Values: `true`, `false`
expiration_offset object Conditionally returned	Specifies the length of time after the date of issue for which the cards are valid. Allowable Values: `unit`, `value`
expiration_offset.unit string Conditionally returned	Specifies the units for the `value` field in this object. Allowable Values: `YEARS`, `MONTHS`, `DAYS`, `HOURS`, `MINUTES`, `SECONDS` Default value: `YEARS`
expiration_offset.value integer Conditionally returned	Specifies the number of time units (as defined by the `unit` field in this object) for which the cards are valid. In other words, cards expire `value` x `unit` after the date of issue. This number is rounded as follows: - YEARS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 Jan 2021 and `value = 1`, the cards expire on the last day of Jan 2022. - MONTHS – Rounds up to the last second of the last day of the month of expiration. For example, if the issue date is 1 May 2022 and `value = 1`, the cards expire on the last day of June 2022. - DAYS – Rounds up to the last second of the day of expiration. - HOURS, MINUTES, SECONDS – No rounding. Allowable Values: Any positive integer Default value: 4
fulfillment object Returned	Specifies certain physical characteristics of a card, as well as bulk shipment information. This object is returned if it exists in the resource. Allowable Values: `card_personalization`, `shipping`
fulfillment.card_personalization object Returned	Specifies personalized attributes to be added to the card. Allowable Values: `carrier`, `images`, `perso_type`, `text`
fulfillment.card_personalization.carrier object Conditionally returned	Specifies attributes of the card carrier. Allowable Values: `logo_file`, `logo_thumbnail_file`, `message_file`, `message_line`, `template_id`
fulfillment.card_personalization.carrier.logo_file string Conditionally returned	Specifies an image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.carrier.logo_thumbnail_file string Conditionally returned	Specifies a thumbnail-sized rendering of the image specified in the `logo_file` field. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.carrier.message_file string Conditionally returned	Specifies a text file containing a custom message to print on the card carrier. Allowable Values: Contains the name of the text file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.carrier.message_line string Conditionally returned	Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max
fulfillment.card_personalization.carrier.template_id string Conditionally returned	Specifies the card carrier template to use. Allowable Values: Card carrier template ID
fulfillment.card_personalization.images object Conditionally returned	Specifies personalized images that appear on the card. Allowable Values: `card`, `carrier`, `carrier_return_window`, `signature`
fulfillment.card_personalization.images.card object Conditionally returned	Specifies personalized images that appear on the card. Allowable Values: `name`, `thermal_color`
fulfillment.card_personalization.images.card.name string Conditionally returned	Specifies a PNG image to display on the card. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.images.card.thermal_color string Conditionally returned	Specifies the color of the image displayed on the card. Allowable Values: Contains the name of the color and must match one of the provider’s predefined colors.
fulfillment.card_personalization.images.carrier object Conditionally returned	Specifies personalized images that appear on the card carrier. Allowable Values: `message_1`, `name`
fulfillment.card_personalization.images.carrier.message_1 string Conditionally returned	Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max
fulfillment.card_personalization.images.carrier.name string Conditionally returned	Specifies a PNG image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.images.carrier_return_window object Conditionally returned	Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: `name`
fulfillment.card_personalization.images.carrier_return_window.name string Conditionally returned	Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.images.signature object Conditionally returned	Specifies a PNG image of the cardholder’s signature. Allowable Values: `name`
fulfillment.card_personalization.images.signature.name string Conditionally returned	Specifies a PNG image of the cardholder’s signature. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
fulfillment.card_personalization.perso_type string Conditionally returned	Specifies the type of card personalization. Allowable Values: `EMBOSS`, `LASER`, `FLAT`
fulfillment.card_personalization.text object Returned	Specifies personalized text that appears on the card. Allowable Values: `name_line_1`, `name_line_2`, `name_line_3`
fulfillment.card_personalization.text.name_line_1 object Returned	Specifies the first line of personalized text that appears on the card. Allowable Values: `name_line_1.value` 21 char max; if `name_line_1_numeric_postfix` is `true`, 14 char max. Strings longer than the character limit are truncated.
fulfillment.card_personalization.text.name_line_1.value string Conditionally returned	Line of personalized text printed on the card. Allowable Values: 21 char max
fulfillment.card_personalization.text.name_line_2 object Conditionally returned	Specifies the second line of personalized text that appears on the card. Allowable Values: `name_line_2.value`
fulfillment.card_personalization.text.name_line_2.value string Conditionally returned	Line of personalized text printed on the card. Allowable Values: 21 char max
fulfillment.card_personalization.text.name_line_3 object Conditionally returned	Specifies the third line of personalized text that appears on the card. Allowable Values: `name_line_3.value`
fulfillment.card_personalization.text.name_line_3.value string Conditionally returned	Line of personalized text printed on the card. Allowable Values: 21 char max
fulfillment.shipping object Conditionally returned	Specifies shipping details for the order. This object is returned if it exists in the resource. Allowable Values: `care_of_line`, `method`, `recipient_address`, `return_address`
fulfillment.shipping.care_of_line string Conditionally returned	Specifies the value of the care of (C/O) line on the mailing carrier. This field is returned if it exists in the resource. Allowable Values: 255 char max
fulfillment.shipping.method string Conditionally returned	Specifies the shipping service. This field is returned if it exists in the resource. Allowable Values: `LOCAL_MAIL`, `LOCAL_MAIL_PACKAGE`, `GROUND`, `TWO_DAY`, `OVERNIGHT`, `INTERNATIONAL`, `INTERNATIONAL_PRIORITY`, `LOCAL_PRIORITY`, `FEDEX_EXPEDITED`, `FEDEX_REGULAR`, `UPS_EXPEDITED`, `UPS_REGULAR`, `USPS_EXPEDITED`, `USPS_REGULAR`
fulfillment.shipping.recipient_address object Conditionally returned	Address to which the order will be shipped. This field is returned if it exists in the resource. Allowable Values: Existing `recipient_address` object
fulfillment.shipping.recipient_address.address1 string Conditionally returned	Number and street of the address. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
fulfillment.shipping.recipient_address.address2 string Conditionally returned	Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
fulfillment.shipping.recipient_address.city string Conditionally returned	City of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max
fulfillment.shipping.recipient_address.country string Conditionally returned	Country of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name “Spain”. The ISO maintains the full list of country codes.
fulfillment.shipping.recipient_address.first_name string Conditionally returned	First name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max
fulfillment.shipping.recipient_address.last_name string Conditionally returned	Last name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max
fulfillment.shipping.recipient_address.middle_name string Conditionally returned	Middle name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max
fulfillment.shipping.recipient_address.phone string Conditionally returned	Telephone number of the addressee. This field is returned if it exists in the resource. Allowable Values: 20 char max
fulfillment.shipping.recipient_address.postal_code string Conditionally returned	Postal code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max
fulfillment.shipping.recipient_address.state string Conditionally returned	State or province of the address. This field is returned if it exists in the resource. Allowable Values: 32 char max
fulfillment.shipping.recipient_address.zip string Conditionally returned	United States ZIP code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max
fulfillment.shipping.return_address object Conditionally returned	Address to which the order will be returned if shipping fails. This object is returned if it exists in the resource. Allowable Values: Existing `return_address` object
fulfillment.shipping.return_address.address1 string Conditionally returned	Number and street of the address. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
fulfillment.shipping.return_address.address2 string Conditionally returned	Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
fulfillment.shipping.return_address.city string Conditionally returned	City of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max
fulfillment.shipping.return_address.country string Conditionally returned	Country of the address. This field is returned if it exists in the resource. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name “Spain”. The ISO maintains the full list of country codes.
fulfillment.shipping.return_address.first_name string Conditionally returned	First name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max
fulfillment.shipping.return_address.last_name string Conditionally returned	Last name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max
fulfillment.shipping.return_address.middle_name string Conditionally returned	Middle name of the addressee. This field is returned if it exists in the resource. Allowable Values: 40 char max
fulfillment.shipping.return_address.phone string Conditionally returned	Telephone number of the addressee. This field is returned if it exists in the resource. Allowable Values: 20 char max
fulfillment.shipping.return_address.postal_code string Conditionally returned	Postal code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max
fulfillment.shipping.return_address.state string Conditionally returned	State or province of the address. This field is returned if it exists in the resource. Allowable Values: 32 char max
fulfillment.shipping.return_address.zip string Conditionally returned	United States ZIP code of the address. This field is returned if it exists in the resource. Allowable Values: 10 char max
name_line1_end_index integer Conditionally returned	This field is included if your bulk card order has been processed. You can use the `name_line1_start_index` and `name_line1_end_index` fields to identify the cards and users associated with the order. For example, if the start index is “1” and the end index is “3”, the card tokens are “card-1”, “card-2”, and “card-3”, and the user tokens are “user-1”, “user-2”, and “user-3”. See Create bulk card order for more information about the automatic generation and naming of cards and users. Allowable Values: Any positive integer
name_line1_start_index integer Conditionally returned	This field is included if your bulk card order has been processed. You can use the `name_line1_start_index` and `name_line1_end_index` fields to identify the cards and users associated with the order. For example, if the start index is “1” and the end index is “3”, the card tokens are “card-1”, “card-2”, and “card-3”, and the user tokens are “user-1”, “user-2”, and “user-3”. See Create bulk card order for more information about the automatic generation and naming of cards and users. Allowable Values: Any positive integer
name_line_1_numeric_postfix boolean Conditionally returned	If set to `true`, the unique numeric postfix appended to each card’s token field is also appended to the card’s `fulfillment.card_personalization.text.name_line_1.value` field. Allowable Values: `true`, `false`
name_line_1_random_postfix boolean Conditionally returned	If set to `true`, the unique random postfix appended to each card’s token field is also appended to the card’s `fulfillment.card_personalization.text.name_line_1.value` field. This field is returned if it exists in the resource. Allowable Values: `true`, `false`
provider_ship_date datetime Conditionally returned	Date and time when the card provider shipped the bulk card order, in UTC. This field is included if your bulk card order has shipped. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
provider_shipping_method string Conditionally returned	Shipping method used by the card provider. `United_Postal_Service`, for example. This field is included if your bulk card order has shipped. Allowable Values: String
provider_tracking_number string Conditionally returned	A tracking number is included only if your card provider is Arroweye Solutions. This field is included if your bulk card order has shipped. Allowable Values: String
token string Returned	Unique identifier of the bulk card order. Allowable Values: 1–36 chars
user_association object Conditionally returned	Associates each card with a user. Allowable Values: `single_inventory_user`, `single_inventory_user_token`
user_association.single_inventory_user boolean Conditionally returned	Set to `true` to associate all cards with the same user. Set to `false` to associate each card with a different user. When set to `false`, users are generated automatically and associated with the cards. Allowable Values: `true`, `false` Default value: `false`
user_association.single_inventory_user_token string Conditionally returned	If `single_inventory_user=true`, use this field to specify the token of an existing user. All cards in the order will be associated with this user. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "token": "bulk_06_token",
  "expedite": false,
  "fulfillment": {
    "shipping": {
      "method": "UPS_REGULAR",
      "return_address": {
        "first_name": "Shipping",
        "last_name": "R_US",
        "address1": "1222 Blake Street",
        "city": "Berkeley",
        "state": "CA",
        "postal_code": "94702",
        "country": "USA",
        "phone": "5102222222"
      },
      "recipient_address": {
        "first_name": "Saki",
        "last_name": "Dogger",
        "address1": "1255 Lake Street",
        "city": "Oakland",
        "state": "CA",
        "postal_code": "94611",
        "country": "USA",
        "phone": "510-333-3333"
      }
    },
    "card_personalization": {
      "text": {
        "name_line_1": {
          "value": "Saki Dogger"
        },
        "name_line_2": {
          "value": "Aegis Fleet Services"
        }
      },
      "carrier": {
        "name": "my_carrier_logo.png",
        "message_line": "my message"
      },
      "images": {
        "card": {
          "name": "my_card_logo.png",
          "thermal_color": "Black"
        },
        "signature": {
          "name": "my_signature.png"
        },
        "carrier_return_window": {
          "name": "my_return_address_image.png"
        }
      }
    }
  },
  "card_product_token": "my_card_product_02",
  "card_allocation": 3,
  "user_association": {
    "single_inventory_user": false
  },
  "name_line_1_numeric_postfix": true,
  "expiration_offset": {
    "unit": "YEARS",
    "value": 10
  },
  "created_time": "2022-03-06T00:06:34Z",
  "name_line1_start_index": 1,
  "name_line1_end_index": 3,
  "card_fulfillment_time": "2022-03-07T23:59:44Z",
  "provider_ship_date": "2022-03-08T00:00:00Z",
  "provider_shipping_method": "United_Parcel_Service",
  "provider_tracking_number": "982247",
  "api": "bulkissuances",
  "endpoint": "/bulkissuances/{token}",
  "method": "get",
  "cp_id": 1,
  "bc_id": 1
}

Core API Basics

SDKs

Credentials

Account Holders

Funding

Just-in-Time Funding

Cards

Digital Wallets

Spend Control

Accounts

Transactions

3D Secure

Real-Time Decisioning

Disputes

Digital Banking

Credit Programs

Credit Account Management

Credit Account Servicing

Credit Reward Accounts

Testing

Webhooks

Bulk Card Orders

Create bulk card order

Request body

Sample request body

Response body

Sample response body

List bulk card orders

URL query parameters

Response body

Sample response body

Retrieve bulk card order

URL path parameters

Response body

Sample response body

Core API Basics

SDKs

Credentials

Account Holders

Funding

Just-in-Time Funding

Cards

Digital Wallets

Spend Control

Accounts

Transactions

3D Secure

Real-Time Decisioning

Disputes

Digital Banking

Credit Programs

Credit Account Management

Credit Account Servicing

Credit Reward Accounts

Testing

Webhooks

​Create bulk card order

​Request body

​Sample request body

​Response body

​Sample response body

​List bulk card orders

​URL query parameters

​Response body

​Sample response body

​Retrieve bulk card order

​URL path parameters

​Response body

​Sample response body

Create bulk card order

Request body

Sample request body

Response body

Sample response body

List bulk card orders

URL query parameters

Response body

Sample response body

Retrieve bulk card order

URL path parameters

Response body

Sample response body