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: ...' \
  -d '{
    "result_version": "1.2"
  }'

await client.accountUpdater.jobs.create({
  resultVersion: "1.2",
});

await client.AccountUpdater.Jobs.CreateAsync(new CreateAccountUpdaterJobRequest
{
  ResultVersion = "1.2"
});

AccountUpdaterJob job = new AccountUpdaterClient(ClientOptions.builder().build())
    .jobs()
    .create(CreateAccountUpdaterJobRequest.builder()
        .resultVersion("1.2")
        .build());

client.account_updater.jobs.create(result_version="1.2")

client.AccountUpdater.Jobs.Create(ctx, &accountupdater.CreateAccountUpdaterJobRequest{
  ResultVersion: basistheory.String("1.2"),
})

Request Parameters

Attribute	Required	Type	Default	Description
`deduplicate_tokens`	false	boolean		Whether to deduplicate tokens when performing updates
`configuration_merchant_id`	false	uuid		The tenant merchant whose Account Updater configuration is used for this job. Does not affect which tokens the job can read. See Merchant Scoping and Configuration.
`merchant_id`	false	uuid		Deprecated: use `configuration_merchant_id` instead. Legacy alias kept for backward compatibility with lower precedence.
`result_version`	false	string	`1`	Version of the result CSV format. Accepted values are `1`, `1.1`, and `1.2`.

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.

The result_version parameter controls which columns are included in the result file. See Result Versions for details on the differences between versions.

Merchant Scoping and Configuration

Merchants affect a job in two independent ways:

Token scope is set by the optional BT-MERCHANT-ID request header. Tokens in the request file are read within that merchant's scope, and updated tokens are created under the same merchant. Without the header, the job runs at the tenant level.
Account Updater configuration is selected by the optional configuration_merchant_id parameter, which determines the merchant configuration (the merchant details registered with the card networks during onboarding) used to request updates. When omitted, it defaults to the configuration of the BT-MERCHANT-ID header merchant, then to the tenant-level configuration.

Use Case	How to Configure
Tenant-level tokens using the tenant's configuration	Omit the `BT-MERCHANT-ID` header and `configuration_merchant_id`.
Tenant-level tokens using a merchant's configuration	Omit the `BT-MERCHANT-ID` header and set `configuration_merchant_id`. This is the most common pattern for tenants onboarded with multiple merchant configurations whose tokens are not merchant-scoped.
A merchant's tokens using that merchant's configuration	Send the `BT-MERCHANT-ID` header. The header merchant's configuration is used by default.
A merchant's tokens using a different merchant's configuration	Send the `BT-MERCHANT-ID` header and set `configuration_merchant_id`.

If the selected merchant does not have its own Account Updater configuration, the tenant-level configuration is used.

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/...",
  "errors": null,
  "requests": null,
  "results": null
}

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": "completed",
  "created_by": "2c8f4156-4ac6-5e71-9e03-8811fd6bc514",
  "created_at": "2024-04-09T13:56:37.864Z",
  "download_url": "https://bt-prod-us-east-2-account-updater-data.s3.us-east-2.amazonaws.com/...",
  "errors": null,
  "requests": 1000,
  "results": {
    "UPD_PAN": 45,
    "NO_UPDATE": 856,
    "WRN_CLOSED_ACCOUNT": 8
  }
}

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": "completed",
      "created_by": "2c8f4156-4ac6-5e71-9e03-8811fd6bc514",
      "created_at": "2024-04-09T13:56:37.864Z",
      "download_url": "https://bt-prod-us-east-2-account-updater-data.s3.us-east-2.amazonaws.com/...",
      "errors": null,
      "requests": 1000,
      "results": {
        "UPD_PAN": 45,
        "NO_UPDATE": 856,
        "WRN_CLOSED_ACCOUNT": 8
      }
    },
    ...
  ]
}

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 4-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`	(Ignored) Any values in this column are ignored. Merchant scoping is controlled by the `BT-MERCHANT-ID` request header instead; leave this column empty.	false

To scope a job's tokens to a specific merchant, send the BT-MERCHANT-ID request header when creating the job; see Merchant Scoping and Configuration. Tokens in the file are then read within that merchant's scope, and rows referencing tokens outside it fail with ERR_MERCHANT_MISMATCH. The values of the legacy merchant_id column are ignored.

Example

token,expiration_year,expiration_month,merchant_id
d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4,,,
f32bc1b4-5c3a-45a3-9ee2-392a1c475d53,2030,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_year`	The expiration year that was originally sent.	false
`expiration_month`	The `expiration_month` that was sent in the request file.	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_year`	The new expiration year returned from the update.	false
`new_expiration_month`	The new expiration month returned from the update.	false
`result_code`	Code summarizing the processing status of the row. See Result Codes below for details.	true
`new_fingerprint`	The fingerprint of the new `card` token. Only included when `result_version` is `1.1` or higher.	false (only in version `1.1` or higher)
`new_brand`	The card brand of the new `card` token (e.g. `visa`, `mastercard`). Only included when `result_version` is `1.1` or higher.	false (only in version `1.1` or higher)
`new_last4`	The last 4 digits of the new `card` token's card number. Only included when `result_version` is `1.2` or higher.	false (only in version `1.2` or higher)

Result Versions

The result_version parameter on the Create Job request controls which columns are included in the result CSV.

Version	Description
`1`	Default. Returns the base columns: `token`, `expiration_year`, `expiration_month`, `new_token`, `new_expiration_year`, `new_expiration_month`, and `result_code`.
`1.1`	Adds `new_fingerprint` and `new_brand` columns after `result_code`. These columns contain the fingerprint and card brand of the newly created token, allowing you to identify updated cards without making a separate API call to retrieve the token.
`1.2`	Adds a `new_last4` column after `new_brand`, containing the last 4 digits of the newly created token's card number. Includes all columns from version `1.1`.

Example (version `1`)

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,2030,02,,,,WRN_CLOSED_ACCOUNT

Example (version `1.1`)

token,expiration_year,expiration_month,new_token,new_expiration_year,new_expiration_month,result_code,new_fingerprint,new_brand
d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4,,,b2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4,,,UPD_PAN,4DdMqM2rHjk3HPq9A3mVRnLFfkz8JMbRVmG93jFp87K2,visa
f32bc1b4-5c3a-45a3-9ee2-392a1c475d53,2030,02,,,,WRN_CLOSED_ACCOUNT,,

Example (version `1.2`)

token,expiration_year,expiration_month,new_token,new_expiration_year,new_expiration_month,result_code,new_fingerprint,new_brand,new_last4
d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4,,,b2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4,,,UPD_PAN,4DdMqM2rHjk3HPq9A3mVRnLFfkz8JMbRVmG93jFp87K2,visa,4242
f32bc1b4-5c3a-45a3-9ee2-392a1c475d53,2030,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
`requests`	integer	Total number of records in the request file. Populated after processing completes.
`results`	object	Count of each result code across all processed rows (e.g. `{"UPD_PAN": 45, "NO_UPDATE": 856}`). Populated after processing completes.
`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​

Merchant Scoping and Configuration​

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​

Result Versions​

Example (version 1)​

Example (version 1.1)​

Example (version 1.2)​

Resources​

Account Updater Job​

Job Statuses​

Create Account Updater Batch Job

Permissions

Expiration

Request

Request Parameters

Merchant Scoping and Configuration

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

Result Versions

Example (version `1`)

Example (version `1.1`)

Example (version `1.2`)

Resources

Account Updater Job

Job Statuses