processCardImport

Overview

This method processes a validated card import batch. Rows classified as create or update are created or updated, provided you have the required permission. Rows classified as invalid, duplicate or unauthorized are skipped and keep their classification.

When processing finishes, the batch is updated with a final status and summary counts, and a result CSV is generated.

A batch can only be processed once.

This API is part of the card import process:

createCardImport – upload and validate the CSV file.
getCardImportErrors – download the rows that failed validation (optional).
processCardImport – create and update the valid cards.
getCardImportResult – download the final outcome for every row.

This method only requires an authenticated user. Permissions are checked for each row: create rows need the Cards:Create permission and update rows need the Cards:Update permission. Rows you are not authorised to process are classified as unauthorized rather than blocking the request.

Permissions

The permissions for this api are stored in [gb_api_permissions]permission as 'Cards:Create' and 'Cards:Update'.

Only roles with a stored link to these permissions in [gb_role_api_permissions] can create or update cards through this api.

HTTP Method

Use the HTTP Method 'POST' for consuming this web service.

URL Examples

https://api.demo.catch-e.com/fm/cards/imports/{import_batch_id}/process https://api.{{environment}}.catch-e.com/fm/cards/imports/{import_batch_id}/process https://api.test.catch-e.com/fm/cards/imports/{import_batch_id}/process

Input Fields (Header)

Key	Format	Notes	Mandatory
Audit-User-Id	string	(Optional) User Id to use for audit purposes. Up to 5 digits. Requires the Audit:UserIdOverride permission.	No

Path Parameters

Key	Format	Notes	Field
import_batch_id	string	The `import_batch_id` returned by createCardImport. A positive whole number, up to 10 digits.	Yes

Response Details

Success

201 - Created

The batch was processed. Check summary for the outcome counts.

Field	Format	Notes
import_batch_id	string	The import batch that was processed.
summary.created	integer	Rows created as new cards.
summary.updated	integer	Rows that updated existing cards.
summary.failed	integer	Rows that were attempted but failed during create or update. Their error reasons are recorded in the result CSV.
summary.skipped	integer	Rows not attempted because they were invalid, duplicate or unauthorized.
result_csv_uri	string	Relative URI to download the result CSV with getCardImportResult. Only present when the result file was generated.

{ "import_batch_id": "1234", "summary": { "created": 5, "updated": 3, "failed": 0, "skipped": 2 }, "result_csv_uri": "/fm/cards/imports/1234/result" }

Error Response Details

Validation Message	Comments
401 - Unauthorized	1. You have not authenticated before running this API or 2. The token_timeout of the current session has passed. You need to authenticate again.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized" }

Validation Message	Comments
403 - Forbidden	- You do not have permissions for this request. - Go to System Roles and enter 'web_services' - Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden" }

Validation Message	Comments
404 - Not Found	The specified import batch does not exist.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Not Found", "status": 404, "detail": "Not Found" }

Validation Message	Comments
406 - Not Acceptable	The Accept header of the request does not match a response format this API supports.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Not Acceptable", "status": 406, "detail": "Not Acceptable" }

Validation Message	Comments
409 - Conflict	The batch has already been processed and cannot be processed again.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Conflict", "status": 409, "detail": "Conflict" }

Validation Message	Comments
422 - Unprocessable Entity	The batch exists but has not yet been validated (the upload step is not complete).

{ "warning_messages": {}, "validation_messages": { "fieldName": { "validationExceptionCode": "A textual description of the validation exception" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation" }

Validation Message	Comments
500 - Internal Error	An unexpected error occurred on the server.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "string", "status": 599, "detail": "string" }

Validation Message	Comments
default - Unexpected Error	Any other unexpected error.

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "string", "status": 599, "detail": "string" }