Writes and operation receipts

Most integrations can use the result returned by a successful write directly. Checking an operation receipt is optional; it is useful for troubleshooting or retrieving a previously recorded outcome.

The server assigns an operation identifier to writes. You do not need to invent or send an idempotency key. The response metadata can include:

{
  "requestId": "request-identifier",
  "operationId": "operation-identifier",
  "status": "COMPLETED"
}

requestId identifies the HTTP request for troubleshooting. operationId identifies the recorded write, and status describes the server invocation.

For example, creating a scheduled campaign can return COMPLETED: the API finished creating the campaign. Its messages may still be waiting for their scheduled time. Save the operation identifier if your integration needs to look up that creation result later.

Check an operation

curl --fail-with-body \
  "$SUBSTY_API_URL/v1/agencies/$SUBSTY_AGENCY_ID/operations/$SUBSTY_OPERATION_ID" \
  --header "Authorization: Bearer $SUBSTY_API_KEY"

Receipt access remains tied to the caller and their authorization. A receipt is not a way to read another client’s activity.

For a queued action, COMPLETED means the invocation completed; it does not promise the creator platform has already delivered the scheduled message, publication, or other downstream job. Inspect the returned resource or queue state where the endpoint provides it.

Retry carefully

Submitting the same write again can create another action. If you received an operation identifier and the outcome is uncertain, check that receipt and reconcile the resource before retrying. Use bounded polling with backoff and respect the shared rate limit.

If the connection drops before you receive the operation identifier, you cannot use this endpoint to recover the receipt. Check the affected resource, such as the campaign list, before deciding whether to submit the write again. Receipts do not automatically deduplicate repeated requests.

Some operations expose waitSeconds and maxEvents controls. These appear as query parameters only on the endpoints that support them. They are not universal options.