Cards

Upload and validate a card import CSV

Upload a CSV file for a given supplier, validate every row, classify each row as create, update, invalid, duplicate, or unauthorized, and persist row-level results in fm_card_imports. A batch header record is created in gb_imports (interface=card_services, service=importCards).

POST

/fm/cards/imports

curl --request POST \
  --url https://api.catch-e.com/fm/cards/imports \
  --header 'Authorization: <api-key>' \
  --header 'Audit-User-Id: <string>' \
  --form 'data=<string>' \
  --form 'supplier_id=<string>'

{
  "error_report_available": true,
  "import_allowed": true,
  "import_batch_id": "42",
  "summary": {
    "duplicate": 5,
    "invalid": 10,
    "total": 120,
    "unauthorized": 10,
    "valid": 95
  }
}

Business rules enforced during validation:

supplier_id must be supplied and must exist as a card-services supplier.
Each row must contain either contract_id or reg_no.
If reg_no resolves to more than one active contract the row is classified as invalid.
Create vs update is determined by the combination of supplier_id + card_number. If a card with that supplier/card-number already exists the row is classified as update; otherwise create.
Duplicate rows within the same file (same supplier_id + card_number) are classified as duplicate.
status_flag must be active or inactive; deleted is rejected.
Missing Cards:Create permission does not invalidate update rows; missing Cards:Update permission does not invalidate create rows. Rows the caller lacks permission to process are classified as unauthorized and reported as skipped during processing.

This method only requires an authenticated identity. Authorisation is enforced per row using the caller's Cards:Create and Cards:Update permissions: create rows require Cards:Create and update rows require Cards:Update. Rows the caller is not authorised to process are classified as unauthorized rather than blocking the request.

Authorizations

Authorizationstringheaderrequired

For accessing the API a valid token must be passed in all the queries in the 'Authorization' header.

A valid token is generated by the API and returned by the /authenticate method by supplying a valid username and password.

The following syntax must be used in the 'Authorization' header :

Bearer aaaaaa/bbbbbb.ccccccc.dddddd

Headers

Audit-User-Idstringheader

(Optional) User Id to use for audit purposes. Requires the Audit:UserIdOverride permission.

Maximum string length: 5

Pattern: ^[1-9]{1}[0-9]*$

Body

datastringrequired

CSV file to import. The file must include a header row. Supported columns:

Column	Required	Notes
`card_number`	Yes	Up to 40 characters
`contract_id`	Conditional	Required if `reg_no` is not supplied
`reg_no`	Conditional	Required if `contract_id` is not supplied. Must resolve to exactly one active contract.
`account_number`	No	Up to 40 characters
`status_flag`	No	`active` or `inactive`. Blank on update leaves existing value unchanged.
`expiry_date`	No	ISO 8601 date (yyyy-MM-dd). Blank on update leaves existing value unchanged.
`activated_date`	No	ISO 8601 date (yyyy-MM-dd). Blank on update leaves existing value unchanged.
`inactivated_date`	No	ISO 8601 date (yyyy-MM-dd). Blank on update leaves existing value unchanged.
`recharge_flag`	No	`yes` or `no`. Blank on update leaves existing value unchanged.
`client_id_recharge`	No	Blank on update leaves existing value unchanged.

supplier_idstringrequired

The supplier to associate with this import batch. Must be a supplier of type card-services.

Maximum string length: 10

Pattern: ^[1-9]{1}[0-9]*$

Response

Batch created and all rows validated. Inspect import_allowed to determine whether the batch may be processed.

error_report_availablebooleanrequired

true if there is at least one invalid, duplicate, or unauthorized row for which an error report can be downloaded via GET /fm/cards/imports/{import_batch_id}/errors.

Example: true

import_allowedbooleanrequired

true if there is at least one create or update row that can be processed. false if every row is invalid, duplicate, or unauthorized — in which case calling the process endpoint would result in no operations being performed.

Example: true

import_batch_idstringrequired

The unique identifier for the newly created import batch record in gb_imports. Use this value in subsequent process, error, and result requests.

Maximum string length: 10

Example: 42

summaryobjectrequired

Counts of rows by validation classification.

Show child attributes

Still need help? Ask the team