Batch Account Updater Enterprise
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.
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
- Node
- C#
- Java
- Python
- Go
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)
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.
Permissions
account-updater:job:read
Request
- cURL
- Node
- C#
- Java
- Python
- Go
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.
Permissions
account-updater:job:read
Request
- cURL
- Node
- C#
- Java
- Python
- Go
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
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. |