Lets you create a new card series for the org. With this API, you can do the following:

• Create auto-generated physical/digital cards for a series.
• Create physical/digital card series with auto card generation disabled.

Prerequisites

• Authentication: Basic or OAuth authentication details
• Access group resource - NA

Resource information

Sample API cURL

curl --location 'https://eu.api.capillarytech.com/v2/card/series/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YTYyZTZm' \
--header 'Cookie: _cfuvid=Y0f3VfLqD8GzrSkhY4oAJF2sdcs4f0RvoHYzuwlgCKM-1751618877635-0.0.1.1-604800000' \
--data '{
  "code":"TestCardSeries123",
  "name":"TestCardSeries123",
  "type":"DIGITAL",
  "expiryDays":1000,
  "maxActiveCardsPerCustomer":1,
  "cardGenerationConfiguration":{
    "prefix":"M2",
    "suffix":"C0",
    "offset":1,
    "length":10,
    "method": "RANDOM_MOD7"
  },
  "cardGenerationEnabled":true,
  "isActive":true,
  "trigger":"SERIES_ID"
}'

Request body parameters

Response parameters

Sample response

{
    "entity": 182,
    "warnings": []
}

Error codes

Additional notes

For all algorithms, the final card number is constructed as:

[prefix] + [generated numeric part] + [suffix]

For algorithms that use a check digit (LUHNALGO, MOD7_ALGO, RANDOM_LUHN, RANDOM_MOD7), one digit is reserved for the check digit.

Available digits for the generated number

Total card length
– prefix length
– suffix length
– check digit (if applicable)

Important constraint for RANDOM method

When you use the RANDOM card generation method, the available numeric space is calculated as total card length minus prefix and suffix lengths. If this space is too small (for example, only one digit), the system may quickly use all possible card numbers. When this happens, you receive the MAX_CARD_NUMBER_REACHED error, and no more unique card numbers can be generated for this series. Always ensure that the numeric space is large enough to support your expected card volume.

Important behaviour when changing algorithms

• Changing the card number generation algorithm does not reset the existing numeric counter.
• The counter is maintained per organisation and card series, not per prefix.
• Updating the prefix does not affect the counter value.

If the current counter value exceeds the number of digits allowed by the new algorithm, card generation fails.

Example scenario:

Consider the scenario below:

• Total card length: 16
• Prefix length: 6
• Check digit: 1
• Available numeric digits: 9

If the existing counter has already reached a 10-digit value, no valid card numbers can be generated.

Resolution

• Increase the total card length, or
• Create a new card series.

Best practices

• Decide the card generation algorithm before issuing cards.
• Avoid changing the algorithm for an active card series.
• When switching to check-digit–based algorithms, ensure enough digits are available for future growth.
• Card length must not be reduced after cards have been generated.
• Do not switch generation method (RANDOM ↔ SEQUENCE) after the card series are live.
• Prefix length reduces numeric space and can exhaust card numbers even when length looks valid.
• Sequence counters are not resettable and persist across config changes.
• When exhaustion occurs, only supported options are: Increase card length, or
  Create a new card series.