/
65 minute read
March 10, 2023

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
Copied

Is this helpful?

Yes
No

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
Copied

Is this helpful?

Yes
No

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
Copied

Is this helpful?

Yes
No

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
Copied

Is this helpful?

Yes
No

Subscribe to our developer newsletter