Invoke Async Reactors

Invoke Asynchronously

Enterprise

Invoke a Reactor by ID without waiting for its execution to finish. The response contains a request ID that you can use to poll for the result.

For configuration and runtime-specific behavior, see Asynchronous node22 Reactors or the legacy Asynchronous node-bt Reactors.

POST

https://api.basistheory.com/reactors/{id}/react-async

Permissions

reactor:invoke

For container-scoped detokenization, use token:use in an Access Rule.

Use reactor:invoke as a direct Application permission. Direct token:use permissions are supported only for backward compatibility and will be deprecated.

Request

The request body depends on the Reactor runtime:

node-bt

cURL

curl 'https://api.basistheory.com/reactors/5b493235-6917-4307-906a-2cd6f1a90b13/react-async' \
  -H 'BT-API-KEY: <PRIVATE_API_KEY>' \
  -H 'Content-Type: application/json' \
  -X 'POST' \
  --data '{
    "args": {
      "card": "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
      "customer_id": "myCustomerId1234"
    }
  }'

Node

const response = await client.reactors.reactAsync(reactorId, {
  args: {
    card: "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
    customer_id: "myCustomerId1234"
  }
});

C#

var response = await client.Reactors.ReactAsyncAsync(
  reactorId,
  new
  {
    args = new
    {
      card = "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
      customer_id = "myCustomerId1234"
    }
  }
);

Python

response = client.reactors.react_async(
    id=reactor_id,
    request={
        "args": {
            "card": "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
            "customer_id": "myCustomerId1234"
        }
    }
)

Java

Map<String, Object> args = new HashMap<>();
args.put("card", "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}");
args.put("customer_id", "myCustomerId1234");

Map<String, Object> request = new HashMap<>();
request.put("args", args);

AsyncReactResponse response = client.reactors()
    .reactAsync(reactorId, request);

Go

request := map[string]any{
  "args": map[string]any{
    "card": "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
    "customer_id": "myCustomerId1234",
  },
}

response, err := client.Reactors.ReactAsync(ctx, reactorId, request)

node22

cURL

curl 'https://api.basistheory.com/reactors/5b493235-6917-4307-906a-2cd6f1a90b13/react-async' \
  -H 'BT-API-KEY: <PRIVATE_API_KEY>' \
  -H 'Content-Type: application/json' \
  -X 'POST' \
  --data '{
    "card": "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
    "customer_id": "myCustomerId1234"
  }'

Node

const response = await client.reactors.reactAsync(reactorId, {
  card: "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
  customer_id: "myCustomerId1234"
});

C#

var response = await client.Reactors.ReactAsyncAsync(
  reactorId,
  new
  {
    card = "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
    customer_id = "myCustomerId1234"
  }
);

Python

response = client.reactors.react_async(
    id=reactor_id,
    request={
        "card": "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
        "customer_id": "myCustomerId1234"
    }
)

Java

Map<String, Object> request = new HashMap<>();
request.put("card", "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}");
request.put("customer_id", "myCustomerId1234");

AsyncReactResponse response = client.reactors()
    .reactAsync(reactorId, request);

Go

request := map[string]any{
  "card": "{{fe7c0a36-eb45-4f68-b0a0-791de28b29e4}}",
  "customer_id": "myCustomerId1234",
}

response, err := client.Reactors.ReactAsync(ctx, reactorId, request)

URI Parameters

Parameter	Required	Type	Default	Description
id	true	uuid	null	The ID of the Reactor

Request Parameters

The request parameters depend on the Reactor runtime:

node-bt

Parameter	Required	Type	Default	Description
args	false	object	null	Arguments sent to the Reactor as req.args.

The callback_url parameter is not supported by /react-async. Legacy node-bt Reactors can use it only through the synchronous /react endpoint, and it is deprecated.

DEPRECATED

node22

Parameter	Required	Type	Default	Description
Request body	false	object	null	Arguments sent directly to the Reactor as event.req.

Response

The endpoint returns 202 Accepted after the request is accepted for asynchronous execution:

{
  "asyncReactorRequestId": "3254626a-e1cf-4616-968f-e08a7ade4fce"
}

Save asyncReactorRequestId with the Reactor ID. Both values are required to retrieve the result.

Retrieve Async Result

Enterprise

Poll the result endpoint using the Reactor ID and asyncReactorRequestId.

GET

https://api.basistheory.com/reactors/{id}/results/{request_id}

Permissions

reactor:invoke

For container-scoped detokenization, use token:use in an Access Rule.

Use reactor:invoke as a direct Application permission. Direct token:use permissions are supported only for backward compatibility and will be deprecated.

Request

cURL

Retrieve an Async Reactor Result

curl 'https://api.basistheory.com/reactors/5b493235-6917-4307-906a-2cd6f1a90b13/results/3254626a-e1cf-4616-968f-e08a7ade4fce' \
  -H 'BT-API-KEY: <PRIVATE_API_KEY>'

Node

const result = await client.reactors.results.get(reactorId, requestId);

C#

var result = await client.Reactors.Results.GetAsync(reactorId, requestId);

Python

result = client.reactors.results.get(
    id=reactor_id,
    request_id=request_id
)

Java

Object result = client.reactors()
    .results()
    .get(reactorId, requestId);

Go

result, err := client.Reactors.Results.Get(ctx, reactorId, requestId)

URI Parameters

Parameter	Required	Type	Default	Description
id	true	uuid	null	The ID of the Reactor.
request_id	true	uuid	null	The asyncReactorRequestId returned when the invocation was accepted. It is also available from the reactor.invoked, reactor.completed, and reactor.failed webhook events.

node22 Results

The following result contract applies to asynchronous node22 Reactors. The records property contains successfully written partial results, including records written before the Reactor later fails or times out.

Pending Response

While an async node22 invocation is running, the endpoint returns 202 Accepted:

{
  "status": "pending"
}

Continue polling until the endpoint returns 200 OK.

Completed Success Response

When an async node22 invocation completes, the endpoint returns 200 OK. result contains the validated node22 Reactor response, and records is always present.

See Partial Results for how to write records during an asynchronous invocation.

Without partial results

If the Reactor did not write any partial results, records is an empty array:

{
  "result": {
    "res": {
      "body": {
        "processed": true
      },
      "statusCode": 200
    }
  },
  "records": []
}

With partial results

When the Reactor writes partial results, each record includes its ID and JSON value:

{
  "result": {
    "res": {
      "body": {
        "processed": true
      },
      "statusCode": 200
    }
  },
  "records": [
    {
      "id": "customer-myCustomerId1234",
      "value": {
        "customer_id": "myCustomerId1234",
        "status": "processed"
      }
    }
  ]
}

Completed Failure Response

If the async runtime fails or times out before producing a final Reactor response, the completed body contains error instead of result. The records property contains any partial results that were written successfully:

See Partial Results for how to preserve records before an invocation fails or times out.

Without partial results

If the Reactor did not write any partial results, partial_records is false and records is an empty array:

{
  "error": {
    "title": "Async Reactor timed out",
    "status": 504,
    "detail": "The async Reactor timed out before it completed.",
    "partial_records": false
  },
  "records": []
}

With partial results

When the Reactor wrote partial results before failing or timing out, partial_records is true and records contains each record:

{
  "error": {
    "title": "Async Reactor timed out",
    "status": 504,
    "detail": "The async Reactor timed out before it completed, but partial records were captured.",
    "partial_records": true
  },
  "records": [
    {
      "id": "customer-myCustomerId1234",
      "value": {
        "customer_id": "myCustomerId1234",
        "status": "processed"
      }
    }
  ]
}

The result endpoint still returns 200 OK. The embedded error.status identifies why the invocation failed.

Errors returned by customer code remain inside the validated result.req or result.res object. The top-level error property is reserved for a failure or timeout that prevented the async runtime from producing a final Reactor response.

node-bt Results

When a node-bt invocation succeeds, the endpoint returns the Reactor's raw output and any tokens created from its tokenize output. If the invocation fails, the endpoint returns the Reactor error.

See the Reactor Response Object for response fields and Reactor Error Handling for failure details. See Asynchronous node-bt Reactors for the webhook and result-retrieval workflow.

Result Status Codes

Status	Runtime	Meaning
200	Both	The invocation completed.
202	node22	The invocation is still running. See Pending Response.
401	Both	The credentials are missing or invalid.
403	Both	The Application lacks permission to retrieve the result.
404	Both	The Reactor or request ID was not found, or the request does not belong to the Reactor. For node-bt, this can also mean the invocation is still running.

Reactor Errors

See Reactor Error Codes for possible errors and common scenarios. See Reactor Error Handling for runtime-specific guidance.

Detokenization

Asynchronous invocations use the same Reactor detokenization behavior and limits as synchronous invocations. Use the request shape for the selected runtime.

Limitations

See Rate Limits for Reactor payload, timeout, and concurrency limits.