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


URI	/v2/card/series/
HTTP method	POST
Pagination	NA
Rate limit	NA
Batch support	NA

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

Parameter (Parameters marked with * are mandatory)	Data Type	Description
code*	String	Unique identifier for the card series.
name	String	Display name for the card series.
type*	String	Type of card. Supported values: `DIGITAL`, `PHYSICAL`.
expiryDays	Integer	Number of days after issuance when the card expires.
maxActiveCardsPerCustomer	Integer	Maximum number of active cards allowed per customer.
cardGenerationConfiguration	Object	Configuration for generating card numbers.
-prefix	String	Starting characters of the card number. Maximum 50 characters are allowed Special characters are not allowed.
-suffix	String	Ending characters of the card number. Maximum 50 characters are allowed. Special characters are not allowed.
-offset	Integer	Starting index or position for card number generation.
-length	Integer	Total length of the card number including prefix and suffix. Minimum 5 characters are required. Maximum 150 characters are allowed.
-method	Enum	Algorithm used for card number generation. Supported values: `DEFAULT`, `LUHNALGO`, `MOD7_ALGO`, `RANDOM`, `RANDOM_LUHN`, `RANDOM_MOD7`. Default value: `DEFAULT` (Incremental- The system keeps a running number for each organisation and card series)
cardGenerationEnabled	Boolean	If true, card generation is enabled for this series.
isActive	Boolean	If true, the card series is active.
trigger	Enum	Specifies the event that triggers card generation. Supported values: `SERIES_ID`, `OU_ID`, `REGISTRATION`.

Response parameters

Parameter	Data Type	Description
entity	Long	Unique ID of the newly created card series.
warnings	Array	List of warnings, if any, generated during processing. Empty if none.

Sample response

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

Error codes

Code	Description
3001	Series code empty
3002	Series already exists
3003	Series type empty
3005	Card length invalid
3006	Card configuration already exists with the same prefix, suffix and cardlength
3007	Card generation config not passed
3022	Card prefix is not a standard string
3023	Card suffix is not a standard string
3024	Card number total length should not be more than 150
3026	Card count exceeds 100000
3028	Card length should not be less than
MAX_CARD_NUMBER_REACHED	All possible card numbers have been generated for the current configuration. No more unique card numbers can be created.

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.

200Successful response