Async Helpers

API for managing async helper resources in Celigo. Async helpers define how integrator.io polls an external system's asynchronous job API: submitting a request, checking its status until completion, and retrieving the result.

An async helper ties together three phases:

• Submit -- initiate the remote job (or reuse the status endpoint).
• Status -- poll until the job reaches a done or error state.
• Result -- fetch the final payload once the status indicates success.

Each phase references an export resource that contains the HTTP configuration (connection, method, relative URI, etc.).

Async helper schema

List async helpers

get

/v1/asynchelpers

Returns an array of all async helper resources in the account.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

limitinteger · min: 1Optional

Maximum number of records to return per page.

afterstringOptional

Opaque cursor for forward pagination. Pass the value from the Link response header (rel="next") to fetch the next page.

externalIdstringOptional

Filter to async helpers matching this exact external identifier.

Responses

200

Array of async helper objects.

application/json

204

No async helpers exist in the account.

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

get/v1/asynchelpers

GET /v1/asynchelpers HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "_id": "64a1b2c3d4e5f60011223344",
    "lastModified": "2026-04-15T14:30:15Z",
    "name": "Salesforce Bulk Query Helper",
    "_templateId": "5c6c135fc802b3146e12eecf",
    "_sourceId": "6256b8c0cddb8a1ba55198d5",
    "http": {
      "submit": {
        "sameAsStatus": true
      },
      "status": {
        "_exportId": "63b1c2d3e4f5a60011334455",
        "statusPath": "status",
        "pollWaitTime": 4,
        "initialWaitTime": 1,
        "inProgressValues": [
          "InProgress",
          "UploadComplete"
        ],
        "doneValues": [
          "JobComplete"
        ],
        "errorValues": [
          "Failed",
          "Aborted"
        ]
      },
      "result": {
        "_exportId": "63c1d2e3f4a5b60011445566"
      }
    }
  }
]

Create an async helper

post

/v1/asynchelpers

Creates a new async helper resource. The referenced http.status._exportId must be an existing export resource. If http.submit.sameAsStatus is false, also set http.submit.resourcePath to extract the async job identifier.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Request body for creating or replacing an async helper resource. All required fields must be present for both POST (create) and PUT (replace) operations.

namestring · min: 1Required

Human-readable name for the async helper.

Example: Salesforce Bulk Query Helper

externalIdstringOptional

External identifier for the async helper. Used by integration apps to reference resources by a stable, human-readable key.

Example: amazon_csv_feed_asynchelper

Responses

201

Async helper created successfully.

application/json

Async helper object as returned by the API.

namestring · min: 1Required

Human-readable name for the async helper.

Example: Salesforce Bulk Query Helper

externalIdstringOptional

External identifier for the async helper. Used by integration apps to reference resources by a stable, human-readable key.

Example: amazon_csv_feed_asynchelper

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyOptional

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyOptional

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_integrationIdstring · objectIdRead-onlyOptional

Reference to the specific integration instance that contains this resource.

This field is only populated for resources that are part of an integration app installation. It contains the unique identifier (_id) of the integration resource that was installed in the account.

The integration instance represents a specific installed instance of an integration app, with its own configuration, settings, and runtime environment.

This reference enables:

• Tracing the resource back to its parent integration instance
• Permission and access control based on integration ownership
• Lifecycle management (enabling/disabling, updating, or uninstalling)

Example: 5f9a7b2c3d4e5f6a7b8c9d0e

_connectorIdstring · objectIdRead-onlyOptional

Reference to the integration app that defines this resource.

This field is only populated for resources that are part of an integration app. It contains the unique identifier (_id) of the integration app (connector) that defines the structure, behavior, and templates for this resource.

The integration app is the published template that can be installed multiple times across different accounts, with each installation creating a separate integration instance (referenced by _integrationId).

This reference enables:

• Identifying the source integration app for this resource
• Determining which template version is being used
• Linking to documentation, support, and marketplace information

Example: 5e8d43a1b9e5a80011a35f1b

_templateIdstring · objectIdRead-onlyOptional

Template this async helper was created from.

Example: 5c6c135fc802b3146e12eecf

_sourceIdstring · objectIdRead-onlyOptional

Source resource this async helper was cloned from.

Example: 6256b8c0cddb8a1ba55198d5

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

post/v1/asynchelpers

POST /v1/asynchelpers HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 353

{
  "name": "Salesforce Bulk Query Helper",
  "http": {
    "submit": {
      "sameAsStatus": true
    },
    "status": {
      "_exportId": "63b1c2d3e4f5a60011334455",
      "statusPath": "status",
      "pollWaitTime": 4,
      "initialWaitTime": 1,
      "inProgressValues": [
        "InProgress",
        "UploadComplete"
      ],
      "doneValues": [
        "JobComplete"
      ],
      "errorValues": [
        "Failed",
        "Aborted"
      ]
    },
    "result": {
      "_exportId": "63c1d2e3f4a5b60011445566"
    }
  }
}

{
  "_id": "64a1b2c3d4e5f60011223344",
  "lastModified": "2026-04-29T14:30:00Z",
  "name": "Salesforce Bulk Query Helper",
  "http": {
    "submit": {
      "sameAsStatus": true
    },
    "status": {
      "_exportId": "63b1c2d3e4f5a60011334455",
      "statusPath": "status",
      "pollWaitTime": 4,
      "initialWaitTime": 1,
      "inProgressValues": [
        "InProgress",
        "UploadComplete"
      ],
      "doneValues": [
        "JobComplete"
      ],
      "errorValues": [
        "Failed",
        "Aborted"
      ]
    },
    "result": {
      "_exportId": "63c1d2e3f4a5b60011445566"
    }
  }
}

Get an async helper

get

/v1/asynchelpers/{_id}

Returns a single async helper resource by its ID.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Async helper ID.

Responses

200

The async helper record.

application/json

Async helper object as returned by the API.

namestring · min: 1Required

Human-readable name for the async helper.

Example: Salesforce Bulk Query Helper

externalIdstringOptional

External identifier for the async helper. Used by integration apps to reference resources by a stable, human-readable key.

Example: amazon_csv_feed_asynchelper

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyOptional

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyOptional

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_integrationIdstring · objectIdRead-onlyOptional

Reference to the specific integration instance that contains this resource.

This field is only populated for resources that are part of an integration app installation. It contains the unique identifier (_id) of the integration resource that was installed in the account.

The integration instance represents a specific installed instance of an integration app, with its own configuration, settings, and runtime environment.

This reference enables:

• Tracing the resource back to its parent integration instance
• Permission and access control based on integration ownership
• Lifecycle management (enabling/disabling, updating, or uninstalling)

Example: 5f9a7b2c3d4e5f6a7b8c9d0e

_connectorIdstring · objectIdRead-onlyOptional

Reference to the integration app that defines this resource.

This field is only populated for resources that are part of an integration app. It contains the unique identifier (_id) of the integration app (connector) that defines the structure, behavior, and templates for this resource.

The integration app is the published template that can be installed multiple times across different accounts, with each installation creating a separate integration instance (referenced by _integrationId).

This reference enables:

• Identifying the source integration app for this resource
• Determining which template version is being used
• Linking to documentation, support, and marketplace information

Example: 5e8d43a1b9e5a80011a35f1b

_templateIdstring · objectIdRead-onlyOptional

Template this async helper was created from.

Example: 5c6c135fc802b3146e12eecf

_sourceIdstring · objectIdRead-onlyOptional

Source resource this async helper was cloned from.

Example: 6256b8c0cddb8a1ba55198d5

400

The _id is not a valid ObjectId.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

No async helper exists with the given ID.

application/json

get/v1/asynchelpers/{_id}

GET /v1/asynchelpers/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "_id": "64a1b2c3d4e5f60011223344",
  "lastModified": "2026-04-15T14:30:15Z",
  "name": "Salesforce Bulk Query Helper",
  "_templateId": "5c6c135fc802b3146e12eecf",
  "_sourceId": "6256b8c0cddb8a1ba55198d5",
  "http": {
    "submit": {
      "sameAsStatus": true
    },
    "status": {
      "_exportId": "63b1c2d3e4f5a60011334455",
      "statusPath": "status",
      "pollWaitTime": 4,
      "initialWaitTime": 1,
      "inProgressValues": [
        "InProgress",
        "UploadComplete"
      ],
      "doneValues": [
        "JobComplete"
      ],
      "errorValues": [
        "Failed",
        "Aborted"
      ]
    },
    "result": {
      "_exportId": "63c1d2e3f4a5b60011445566"
    }
  }
}

Update an async helper

put

/v1/asynchelpers/{_id}

Updates an existing async helper with the provided data. This is a full replacement — all required fields must be included in the request body.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Async helper ID.

Body

Request body for creating or replacing an async helper resource. All required fields must be present for both POST (create) and PUT (replace) operations.

namestring · min: 1Required

Human-readable name for the async helper.

Example: Salesforce Bulk Query Helper

externalIdstringOptional

External identifier for the async helper. Used by integration apps to reference resources by a stable, human-readable key.

Example: amazon_csv_feed_asynchelper

Responses

200

Async helper updated successfully.

application/json

Async helper object as returned by the API.

namestring · min: 1Required

Human-readable name for the async helper.

Example: Salesforce Bulk Query Helper

externalIdstringOptional

External identifier for the async helper. Used by integration apps to reference resources by a stable, human-readable key.

Example: amazon_csv_feed_asynchelper

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyOptional

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyOptional

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_integrationIdstring · objectIdRead-onlyOptional

Reference to the specific integration instance that contains this resource.

This field is only populated for resources that are part of an integration app installation. It contains the unique identifier (_id) of the integration resource that was installed in the account.

The integration instance represents a specific installed instance of an integration app, with its own configuration, settings, and runtime environment.

This reference enables:

• Tracing the resource back to its parent integration instance
• Permission and access control based on integration ownership
• Lifecycle management (enabling/disabling, updating, or uninstalling)

Example: 5f9a7b2c3d4e5f6a7b8c9d0e

_connectorIdstring · objectIdRead-onlyOptional

Reference to the integration app that defines this resource.

This field is only populated for resources that are part of an integration app. It contains the unique identifier (_id) of the integration app (connector) that defines the structure, behavior, and templates for this resource.

The integration app is the published template that can be installed multiple times across different accounts, with each installation creating a separate integration instance (referenced by _integrationId).

This reference enables:

• Identifying the source integration app for this resource
• Determining which template version is being used
• Linking to documentation, support, and marketplace information

Example: 5e8d43a1b9e5a80011a35f1b

_templateIdstring · objectIdRead-onlyOptional

Template this async helper was created from.

Example: 5c6c135fc802b3146e12eecf

_sourceIdstring · objectIdRead-onlyOptional

Source resource this async helper was cloned from.

Example: 6256b8c0cddb8a1ba55198d5

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

put/v1/asynchelpers/{_id}

PUT /v1/asynchelpers/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 364

{
  "name": "Salesforce Bulk Query Helper",
  "http": {
    "submit": {
      "sameAsStatus": true
    },
    "status": {
      "_exportId": "63b1c2d3e4f5a60011334455",
      "statusPath": "status",
      "pollWaitTime": 4,
      "initialWaitTime": 1,
      "inProgressValues": [
        "InProgress",
        "UploadComplete"
      ],
      "doneValues": [
        "JobComplete"
      ],
      "errorValues": [
        "Failed",
        "Aborted",
        "TimedOut"
      ]
    },
    "result": {
      "_exportId": "63c1d2e3f4a5b60011445566"
    }
  }
}

{
  "_id": "64a1b2c3d4e5f60011223344",
  "lastModified": "2026-04-16T09:05:42Z",
  "name": "Salesforce Bulk Query Helper",
  "http": {
    "submit": {
      "sameAsStatus": true
    },
    "status": {
      "_exportId": "63b1c2d3e4f5a60011334455",
      "statusPath": "status",
      "pollWaitTime": 4,
      "initialWaitTime": 1,
      "inProgressValues": [
        "InProgress",
        "UploadComplete"
      ],
      "doneValues": [
        "JobComplete"
      ],
      "errorValues": [
        "Failed",
        "Aborted",
        "TimedOut"
      ]
    },
    "result": {
      "_exportId": "63c1d2e3f4a5b60011445566"
    }
  }
}

Delete an async helper

delete

/v1/asynchelpers/{_id}

Deletes an async helper. The resource is soft-deleted and retained in the recycle bin for 30 days before permanent removal. If other resources reference this async helper (e.g. exports, flows), the delete is blocked — use GET /v1/asynchelpers/{_id}/dependencies to discover dependents first.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Async helper ID.

Responses

204

Async helper deleted successfully.

No content

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

The resource has dependents that must be deleted first. Each entry in the errors array names one blocking resource.

application/json

delete/v1/asynchelpers/{_id}

DELETE /v1/asynchelpers/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

List dependencies of an async helper

get

/v1/asynchelpers/{_id}/dependencies

Returns the set of resources that depend on the specified resource. The response is an object whose keys are dependent-resource types (e.g. flows, imports) and whose values are arrays of dependency entries.

Returns {} for both zero-dependency and nonexistent IDs.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Resource ID.

Responses

200

Dependency map. Keys are resource-type strings; values are arrays of dependency entries. Returns {} when no dependents exist.

application/json

Map of dependent-resource types to arrays of dependency entries. Keys are plural resource type strings (e.g. flows, imports, connections). An empty object {} means no dependents.

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

get/v1/asynchelpers/{_id}/dependencies

GET /v1/asynchelpers/{_id}/dependencies HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{}