Skip to main content

Self-Service Order Status Change (Sandbox Only)

🧪 Sandbox only. This endpoint is available exclusively in non-production environments (sandbox). Calling it against the production base URL returns a 403 Forbidden. It exists so you can drive your own integration testing — cancelling, completing, requesting information, requesting a file, requesting a signature, or adding a service on a test order — without waiting on Swyft staff to do it manually.

You can self-service seven actions on the order you track:

actionWhat it simulates
cancelSwyft cancels the order.
completeThe order is marked completed.
request_informationSwyft opens a rejection asking for more information.
request_fileSwyft opens a rejection asking for an uploaded file.
request_wet_signatureSwyft asks for a document to be signed and physically mailed back.
request_scan_signatureSwyft asks for a document to be signed, scanned and uploaded.
add_dbaSwyft adds a DBA filing to a Foreign Qualification order.

All actions apply to the parent order you track — the order_uuid returned when you created the order. They work on any order type (incorporations, Foreign Qualification, standalone services), except add_dba, which is Foreign Qualification only.

Change order status​

POST {baseUrl}/orders/{order_uuid}/simulate-processing
Authorization: Bearer {token}
Content-Type: application/json
{
  "action": "cancel"
}
FieldTypeNotes
order_uuidstring (path)UUID of the order you are tracking.
actionstringOne of cancel, complete, request_information, request_file, request_wet_signature, request_scan_signature, add_dba.
reasonstringRequired when action is request_information or request_file. Ignored otherwise. Max 1000 characters.
fieldstringOptional. Only meaningful with request_information / request_file. A field key from your order (e.g. business_data.name) returned as the rejection's field. For request_information it also sets the rejection's type to "field" (without it, type is "other"); a request_file rejection is always type: "document". Ignored by every other action. Max 255 characters.

cancel​

Sets the order's lifecycle to cancelled. The order's reported status becomes Cancelled. This endpoint has no self-service "reactivate" action — from the API's perspective the order stays cancelled until Swyft staff reactivate it — so calling cancel again on it returns a 422.

{ "action": "cancel" }

complete​

Fast-forwards the order straight to the Completed processing stage, skipping the normal review → filed → approved pipeline. This is a testing convenience only — it does not represent an order that was actually reviewed or filed.

⚠️ Status only — no fulfillment output. complete changes the order's status and sends the matching webhook, but none of the post-approval work a real completion triggers takes place. In particular, no formation documents are generated (Statement of Organizer, Operating Agreement or Bylaws, Banking Resolution, Minutes, Seller's Permit, Digital Corporate Kit), so they won't appear on Download order documents; follow-up services purchased with a formation (e.g. Initial Report, Certificate of Good Standing, Certified Copy) are not created; and no customer emails are sent. To test document handling, upload your own test documents to the order instead.

The order must currently be active — a cancelled (or otherwise non-active) order returns a 422 and must be reactivated by Swyft staff before it can be completed.

The order must also not currently be reporting Action Required — an order (or, for a bundle, any of its child orders) with an open rejection or pending questionnaire can't be completed until that's resolved; this also returns a 422.

For a bundled order, every line that isn't cancelled is completed along with the parent.

{ "action": "complete" }

request_information​

Opens a rejection on the order, the same mechanism Swyft staff use when they need something from the customer. The order's reported status becomes Action Required and the rejection is received on the Partner, to make it visible or communicated to the customer.

Cancelled orders and already-completed orders can't have a rejection opened — both return a 422.

{
  "action": "request_information",
  "reason": "Please confirm the registered agent's mailing address."
}

Pass field to simulate a rejection about a specific data point you submitted:

{
  "action": "request_information",
  "reason": "The business name is already taken in this state.",
  "field": "business_data.name"
}

Resolve it exactly like any other rejection — see Respond to Order Rejections: the rejection this creates shows up under required_actions.rejections on the order, and POST {baseUrl}/orders/{order_uuid}/rejection closes it.

request_file​

Opens a file request rejection on the order — the same kind Swyft staff open from the CRM when they need a document from the customer. The order's reported status becomes Action Required and the rejection (type: "document") is visible to the customer.

Unlike request_information, a file request isn't closed with a text rejection response: it resolves when you upload a document to the order via Upload Order Documents with the rejection's id as rejection_id. An upload without rejection_id leaves the file request open. See Required files for the full upload/resolution mechanics.

Cancelled orders and already-completed orders can't have a rejection opened — both return a 422.

{
  "action": "request_file",
  "reason": "Signed operating agreement"
}

request_wet_signature​

Opens a wet-signature request — the same request Swyft staff open when a document must be signed by hand and physically returned. A test document named "Document for Signature" is added to the order as the document to sign, and the state's signature instructions are attached. The order's reported status becomes Action Required.

The request appears under required_actions.rejections with type: "wet-signature-request", reason: "Signature required for: Document for Signature.", and the template_document_url / instruction_document_url links described in Signature-required rejections.

A wet-signature request can't be closed through the API — it closes only once Swyft receives the signed document — so in sandbox it stays open until Swyft staff close it. Use cancel if you need to discard the test order.

{ "action": "request_wet_signature" }

request_scan_signature​

Same as request_wet_signature, but opens a scan-signature request (type: "scan-signature-request"): the document is signed, scanned and uploaded back. It closes when you upload the signed scan via Upload Order Documents with the request's id as rejection_id — see Resolving a scan-signature request.

{ "action": "request_scan_signature" }

Each call to either signature action opens a new request with its own new "Document for Signature", so you can open several. Neither takes reason or field (both are ignored if sent). Cancelled orders and already-completed orders return a 422.

add_dba​

Simulates Swyft staff adding a DBA filing to a Foreign Qualification order, in the order's state of foreign qualification. It behaves exactly like a real staff-added service:

add_dba can be called more than once; each call adds another DBA and sends another order_service_added. It takes no reason or field.

Only Foreign Qualification orders accept add_dba — any other order type returns a 422, as do cancelled and already-completed orders.

{ "action": "add_dba" }

Success​

{
  "data": {
    "message": "Order status updated successfully",
    "order_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "success": true
}

Webhooks are sent exactly as if the change had come from Swyft staff: any action that changes the order's reported status emits an order_status_changed webhook for the new status, and add_dba also emits order_service_added.

Errors and edge cases​

  • 403 Forbidden: You called this endpoint against a production base URL. It only works in Sandbox / non-production environments.
  • 422 Validation:
    • action is missing/unrecognized, or reason is missing while action is request_information or request_file.
    • order_uuid belongs to a child line of a bundled order rather than the parent order you track.
    • The order is already in the target state (e.g. calling cancel on an already-cancelled order, or complete on an already-completed order).
    • complete is called on an order that isn't currently active (e.g. a cancelled order), or on an order (or bundle with a child order) currently reporting Action Required.
    • request_information, request_file, request_wet_signature, request_scan_signature or add_dba is called on a cancelled or already-completed order.
    • add_dba is called on an order that isn't a Foreign Qualification order.
  • 401 / 403: The order is not associated with your partner account.