Skip to main content

Batch Account Updater
Enterprise

Account Updater is an Enterprise feature. Request access in the portal.

Create Account Updater Batch Job

Creates an Account Updater Batch Job to update a batch of card tokens. Responds with an Account Updater Job including an upload_url to submit a request CSV file for processing.

POST
https://api.basistheory.com/account-updater/jobs
Copy

Permissions

account-updater:job:create

Expiration

You have one hour to upload a request file, at which time the job and upload url will expire and the job will be removed. Attempting to retrieve an expired job will result in a 404 status code. If a job expires, simply start the process again by creating a new job.

Request

curl "https://api.basistheory.com/account-updater/jobs" \
-X POST \
-H 'Content-Type: application/json' \
-H 'BT-API-KEY: ...'

Response

Returns the created Account Updater Job.

{
"id": "93f3da5e-7887-408c-88ed-b10a5fdb423a",
"tenant_id": "9a63ab82-1d11-59a0-93ab-4e1ec98b9fdd",
"status": "pending",
"created_by": "2c8f4156-4ac6-5e71-9e03-8811fd6bc514",
"created_at": "2024-04-09T13:56:37.864Z",
"expires_at": "2024-04-09T14:56:37.864Z",
"upload_url": "https://bt-prod-us-east-2-account-updater-data.s3.us-east-2.amazonaws.com/..."
}

Get Account Updater Job

Retrieves an Account Updater Job. This endpoint can be used to poll for job failure or completion if webhook callbacks are not desired.

GET
https://api.basistheory.com/account-updater/jobs/{id}
Copy

Permissions

account-updater:job:read

Request

curl "https://api.basistheory.com/account-updater/jobs/93f3da5e-7887-408c-88ed-b10a5fdb423a" \
-H 'BT-API-KEY: ...'

Response

{
"id": "93f3da5e-7887-408c-88ed-b10a5fdb423a",
"tenant_id": "9a63ab82-1d11-59a0-93ab-4e1ec98b9fdd",
"status": "pending",
"created_by": "2c8f4156-4ac6-5e71-9e03-8811fd6bc514",
"created_at": "2024-04-09T13:56:37.864Z",
"expires_at": "2024-04-09T14:56:37.864Z",
"upload_url": "https://bt-prod-us-east-2-account-updater-data.s3.us-east-2.amazonaws.com/..."
}

List Account Updater Jobs

Return a list of all Account Updater Jobs created for the tenant.

GET
https://api.basistheory.com/account-updater/jobs
Copy

Permissions

account-updater:job:read

Request

curl "https://api.basistheory.com/account-updater/jobs" \
-H 'BT-API-KEY: ...'

Sort Order

This endpoint returns newest jobs first.

Query Params

ParamDescription
sizeThe maximum number of jobs to return in the response. Defaults to 20.
startThe cursor at which the result set should start. This is the value of the next cursor returned in the previous response.

Response

Returns a cursor paginated list of Account Updater Jobs.

{
"pagination": {
"next": "Q1JFQVRFRF9BVCMyMDI0LTA0LTI1VDE2OjU4OjA3LjgyMVo=",
"page_size": 20
},
"data": [
{
"id": "93f3da5e-7887-408c-88ed-b10a5fdb423a",
"tenant_id": "9a63ab82-1d11-59a0-93ab-4e1ec98b9fdd",
"status": "pending",
"created_by": "2c8f4156-4ac6-5e71-9e03-8811fd6bc514",
"created_at": "2024-04-09T13:56:37.864Z",
"expires_at": "2024-04-09T14:56:37.864Z",
"upload_url": "https://bt-prod-us-east-2-account-updater-data.s3.us-east-2.amazonaws.com/..."
},
...
]
}

File Format Specifications

Request File Format

Account Updater request CSV files must use the following format:

PropertyDefinitionRequired
tokenA card token to be updated. The expiration date in this token is optional, and if present, will be sent to the networks when requesting updates.true
expiration_year(Optional) The 2-digit expiration year of the account number. This is not required if the card token has expiration_year stored.false
expiration_month(Optional) The 2-digit expiration month of the account number. This is not required if the card token has expiration_month stored.false
merchant_id(Optional) The merchant identifier (if provided by Basis Theory) under which this update request is submittedfalse

Certain Account Updater configurations may require a merchant_id to be submitted in the request file to distinguish between multiple merchants within your tenant. During Account Updater onboarding, Basis Theory will identify whether a merchant_id is required and these values will be provided to you. If you were not provided with merchant_ids during onboarding, leave the merchant_id field empty.

Example

token,expiration_year,expiration_month,merchant_id
d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4,,,
f32bc1b4-5c3a-45a3-9ee2-392a1c475d53,30,02,

Result File Format

We do not consider the addition of columns to this file a breaking change.

The result file is used to communicate any tokens created as a result of an updated account number or expiration date. This file only includes rows that resulted in a successful update, a warning, or an error (see Result Codes for details). Rows that did not result in any updates (i.e. the NO_UPDATE result code), warnings, or errors are omitted from the result file.

Account Updater result CSV files will use the following format:

PropertyDefinitionAlways Returned
tokenThe card token to be updated, as sent in the request filetrue
expiration_monthThe expiration_month that was sent in the request file.false
expiration_yearThe expiration year that was originally sent.false
new_tokenThe new card token created with updated card details. Update any references to this token in your systems.false (only on successful update)
new_expiration_monthThe new expiration month returned from the update.false
new_expiration_yearThe new expiration year returned from the update.false
result_codeCode summarizing the processing status of the row. See Result Codes below for details.true

Example

token,expiration_year,expiration_month,new_token,new_expiration_year,new_expiration_month,result_code
d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4,,,b2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4,,,UPD_PAN
f32bc1b4-5c3a-45a3-9ee2-392a1c475d53,30,02,,,,WRN_CLOSED_ACCOUNT

Resources

Account Updater Job

PropertyTypeDescription
idstringIdentifier for the account updater job
tenant_iduuidThe tenant this job is associated with
statusstringThe job status
expires_atdatetimeTime the upload URL will expire. This property is only returned while the job is in the pending status.
created_byuuidThe id of the application used to create the job
created_atdatetimeTimestamp when this job was created
upload_urlstringThe URL to which the Request File should be uploaded. This will only be returned when the job is in the pending status.
errorsarray<string>An array of error messages encountered when attempting to process the job
download_urlstringThe URL to download the Result File. This will only be returned when the job is in the completed status.

Job Statuses

StatusDescription
pendingThe job has been created and is waiting for the request file to be uploaded.
processingThe job is currently being processed.
completedThe job has been processed and the result file is available for download.
failedThe job failed to process, and the result file is not available. Errors will be included in the job's errors property.