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

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: ...'

await client.accountUpdater.jobs.create();

await client.AccountUpdater.Jobs.CreateAsync();

AccountUpdaterJob job = new AccountUpdaterClient(ClientOptions.builder().build())
    .jobs()
    .create();

client.account_updater.jobs.create()

client.AccountUpdater.Jobs.Create(ctx)

Request Parameters

Attribute	Required	Type	Description
`deduplicate_tokens`	false	boolean	Whether to deduplicate tokens when performing updates

The deduplicate_tokens parameter will override the tenant-level deduplicate tokens setting. If token deduplication is enabled and an account update is received with data matching an existing token's fingerprint, the existing token will be updated and returned instead of creating a new token.

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}

Permissions

account-updater:job:read

Request

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

await client.accountUpdater.jobs.get('93f3da5e-7887-408c-88ed-b10a5fdb423a');

await client.AccountUpdater.Jobs.GetAsync("93f3da5e-7887-408c-88ed-b10a5fdb423a");

AccountUpdaterJob job = new AccountUpdaterClient(ClientOptions.builder().build())
    .jobs()
    .get("93f3da5e-7887-408c-88ed-b10a5fdb423a");

client.account_updater.jobs.get(
  id = "93f3da5e-7887-408c-88ed-b10a5fdb423a"
)

client.AccountUpdater.Jobs.Get(ctx, "93f3da5e-7887-408c-88ed-b10a5fdb423a")

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

Permissions

account-updater:job:read

Request

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

await client.accountUpdater.jobs.list();

await client.AccountUpdater.Jobs.ListAsync(new JobsListRequest());

AccountUpdaterJob job = new AccountUpdaterClient(ClientOptions.builder().build())
  .jobs()
  .list();

client.account_updater.jobs.list()

client.AccountUpdater.Jobs.List(ctx, &accountupdater.JobsListRequest{})

Sort Order

This endpoint returns newest jobs first.

Query Params

Param	Description
`size`	The maximum number of jobs to return in the response. Defaults to 20.
`start`	The 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:

Property	Definition	Required
`token`	A `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 submitted	false

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:

Property	Definition	Always Returned
`token`	The `card` token to be updated, as sent in the request file	true
`expiration_month`	The `expiration_month` that was sent in the request file.	false
`expiration_year`	The expiration year that was originally sent.	false
`new_token`	The new `card` token created with updated card details. Update any references to this token in your systems.	false (only on successful update)
`new_expiration_month`	The new expiration month returned from the update.	false
`new_expiration_year`	The new expiration year returned from the update.	false
`result_code`	Code 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

Property	Type	Description
`id`	string	Identifier for the account updater job
`tenant_id`	uuid	The tenant this job is associated with
`status`	string	The job status
`expires_at`	datetime	Time the upload URL will expire. This property is only returned while the job is in the `pending` status.
`created_by`	uuid	The id of the application used to create the job
`created_at`	datetime	Timestamp when this job was created
`upload_url`	string	The URL to which the Request File should be uploaded. This will only be returned when the job is in the `pending` status.
`errors`	array<string>	An array of error messages encountered when attempting to process the job
`download_url`	string	The URL to download the Result File. This will only be returned when the job is in the `completed` status.

Job Statuses

Status	Description
`pending`	The job has been created and is waiting for the request file to be uploaded.
`processing`	The job is currently being processed.
`completed`	The job has been processed and the result file is available for download.
`failed`	The job failed to process, and the result file is not available. Errors will be included in the job's `errors` property.

Create Account Updater Batch Job​

Permissions​

Expiration​

Request​

Request Parameters​

Response​

Get Account Updater Job​

Permissions​

Request​

Response​

List Account Updater Jobs​

Permissions​

Request​

Sort Order​

Query Params​

Response​

File Format Specifications​

Request File Format​

Example​

Result File Format​

Example​

Resources​

Account Updater Job​

Job Statuses​

Create Account Updater Batch Job

Permissions

Expiration

Request

Request Parameters

Response

Get Account Updater Job

Permissions

Request

Response

List Account Updater Jobs

Permissions

Request

Sort Order

Query Params

Response

File Format Specifications

Request File Format

Example

Result File Format

Example

Resources

Account Updater Job

Job Statuses