Async operations

Follow long-running work, such as adding payees to a group or refreshing an accounting connection's reference data, by polling an operation or subscribing to webhook events. These endpoints return 202 Accepted with an operation.

What you get back

A long-running endpoint answers with 202 Accepted, a Location header pointing at the operation, a Retry-After header with a suggested wait in seconds, and an AsyncOperation body:

HTTP/1.1 202 Accepted
Location: /v3/platform/operations/Ts9mQ4vK2xLp7WzR1nBcHd
Retry-After: 2
Content-Type: application/json

{
  "id": "Ts9mQ4vK2xLp7WzR1nBcHd",
  "operationType": "GroupMemberBulkAdd",
  "status": "Processing",
  "events": {
    "createdAt": "2026-04-02T09:15:03Z"
  },
  "actors": {
    "createdBy": "Hn4dW8kPq2ZxM7vRt5LcJa"
  }
}

The operation id is its own ID. It isn't the ID of the resource the work changes.

The 202 can arrive already finished. If the work completed while the request was open, status is already terminal and result or error is filled in. Check status before you start polling.

Operation fields

Operation types

These are the operationType values you can see today:

Two more types appear on endpoints that aren't built yet. FormSubmission (POST /v3/compliance/forms/{formId}/submit) and NotificationClearByHandle always return an operation that is already Failed with error.code: NotImplemented.

Statuses

A terminal operation never changes again. There is no endpoint to cancel an operation directly.

Poll for the result

1. Read the operation. Use the Retry-After value to determine how long to wait before the next request:

   Bash

   curl "https://api.wingspan.app/v3/platform/operations/Ts9mQ4vK2xLp7WzR1nBcHd" \
     -H "Authorization: Bearer $WINGSPAN_TOKEN"

   Get an operation returns the same body shape, with Retry-After while it's still Processing.

2. While status is Processing, wait for the Retry-After seconds and read it again.

3. When status is terminal, handle the outcome:

   JSON

   // (trimmed)
   {
     "id": "Ts9mQ4vK2xLp7WzR1nBcHd",
     "operationType": "GroupMemberBulkAdd",
     "status": "Completed",
     "events": {
       "createdAt": "2026-04-02T09:15:03Z",
       "completedAt": "2026-04-02T09:15:07Z"
     }
   }

Poll with the same credentials, and the same X-Wingspan-Account if you used one, as the request that started the work. An operation that doesn't exist, has expired, or belongs to someone else returns 404.

Finished operations stay readable for 90 days. After that, they return 404. Store any result data your system needs before the operation expires.

Notification bulk actions

Bulk view and bulk dismiss finish before they respond. The 202 body is already Completed, PartiallyCompleted, or Failed. The response is already final; read status and progress from it and don't poll. The response still carries a Location header, but the operation it names can't be fetched.

Subscribe instead of polling

Subscribe to the Operation.* webhook events to receive notification when an operation finishes: Operation.Created, Operation.Completed, Operation.PartiallyCompleted, Operation.Failed, and Operation.Cancelled. Each event identifies the operation. Read the operation to get its result or error.

These events are about the operation. The resource the work changed may send its own events as well, and those are separate facts, not duplicates. See Webhooks and events.

When an operation fails

• Read error.code and handle it according to the error contract. Include a default case: a failed operation can carry a code that isn't in the error list. Treat any code you don't recognize as a permanent failure of that operation.
• If error.detailCode is operations.CompletionTimeout, Wingspan lost track of the work before it reported an outcome. The work may have finished anyway. Check the state of the affected resources before you start the work again, or you may do it twice.
• For PartiallyCompleted, use progress and result to find the items that failed, fix them, and send a new request for those items.

Operations and idempotency

Send an Idempotency-Key on the request that starts the work. A retry with the same key returns the same operation instead of starting a second one. See Idempotency.

Batches are tracked on the batch

Bulk imports through /v3/platform/batches don't return an AsyncOperation. A batch has its own status and progress counters. See Batches and bulk operations.

Related pages

• Errors
• Idempotency
• Webhooks and events