Respond to Order Rejections (Information Requests)

While Swyft processes an order, our team may raise a rejection — an information request for corrected or additional information - needed to continue the filing (for example, a business name that is too similar to an existing company). When an order has an open rejection, its reported status becomes Action Required. An order that has not been submitted yet keeps reporting Created; its open rejections still appear under required_actions.rejections.

You can resolve these rejections programmatically with the rejection-response endpoint.

All rejections need to be solved, in order for the order to go back to the previous state.

Discovering open rejections

Open rejections are surfaced under required_actions.rejections Get order response (and on the order_status_changed webhook payload):

"required_actions": {
    "rejections": [
        {
            "id": 220742,
            "type": "field",
            "field": "business_name",
            "reason": "Your business name is too similar to another company already in business. Please provide us with a new business name to submit to the state.",
            "message": "Use rejection answer EP to answer rejection."
        }
    ]
}

Each rejection's id is a stable, globally-unique identifier — that is the value you pass to the endpoint below.

The field is the actual Data Point related to the original order creation. You need to pass this attribute on your response.

type is a machine-readable classification of the rejection, so your integration can route each case to the right automated or manual follow-up without parsing reason as free text:

`type`	Meaning
`field`	Wrong, incomplete, or typo'd information in one of the fields you submitted.
`document`	A document is missing or incorrect. Resolve it via the Upload order documents endpoint — see the `message` table below.
`wet-signature-request`	The order needs a document signed with a wet (physical) signature. See Signature-required rejections.
`scan-signature-request`	The order needs a document signed and the signed copy scanned back in. See Signature-required rejections.
`other`	Doesn't match any of the above — including free-text rejections and the EIN rejection. Resolve it via the rejection-response endpoint below unless its `message` says otherwise.

The message field tells you how to resolve the rejection:

`message`	How to resolve
`Use rejection answer EP to answer rejection.`	Submit a text reply with the endpoint below.
`Upload the requested document via the documents EP to answer this rejection.`	The rejection asks for a document, not a text answer — the endpoint below will not close it. Resolve it with the Upload order documents endpoint instead, passing this rejection's `id` as `rejection_id` — doing so also lets you omit `field_key` entirely, since the server derives it from the rejection. This message covers two distinct rejection kinds: an ad-hoc file request, and a required document rejection tied to a specific input field. For a required-document rejection you can alternatively upload with `field_key` set to that field's `key` and skip `rejection_id` altogether, since it's satisfied independently of how many other rejections are open. For a file request there's no such key-based alternative — `rejection_id` is required to resolve it; a plain attachment upload (no `field_key`, no `rejection_id`) leaves the file request open.
The wet-signature instruction (see Signature-required rejections)	Not answerable through either endpoint below — it closes only once Swyft receives the physical signed document.
The scan-signature instruction (see Signature-required rejections)	Not answerable via the rejection-response endpoint, but is resolvable via the Upload order documents endpoint — upload the signed scan with this rejection's `id` as `rejection_id`, same as a file request.

📝 Bundled orders: For an incorporation/bundle order, the parent order's required_actions.rejections list also includes rejections raised on its child lines. The child orders are never exposed individually, so respond using the parent order's uuid and the rejection id — Swyft routes the answer to the correct underlying line automatically.

Signature-required rejections

A wet-signature-request or scan-signature-request rejection carries its own instructional message and, when available, links to the documents needed to complete it:

{
    "id": 220899,
    "type": "wet-signature-request",
    "field": null,
    "reason": "Signature required for: Operating Agreement.",
    "message": "This document requires a wet signature. To proceed with filing, download the document, print it, sign it, and send it to the address listed in the instruction document.",
    "instruction_document_url": "https://.../wet-signature-instructions.pdf",
    "instruction_document_uuid": "9b2f6c1e-4a7d-4e8b-b1f3-2d6a8c0e5f71",
    "template_document_url": "https://.../operating-agreement.pdf",
    "template_document_uuid": "c4d7e2a9-1f3b-4d6e-8a5c-7b9e0f2d4a68"
}

instruction_document_url — how to complete and return the document. May be absent if Swyft hasn't attached instructions for this rejection yet.
template_document_url — the document to sign. May be absent until an agent has attached it to the order.
instruction_document_uuid / template_document_uuid — the same documents' uuid, present whenever the matching *_url is. Pass either as id to the Download order documents endpoint to fetch that document directly (for example, to get a fresh download link once the short-lived *_url has expired). Can be null for a document attached before document UUIDs were introduced.

Wet (wet-signature-request) and scan (scan-signature-request) close differently:

A wet-signature rejection is never resolved through the API — it closes only once Swyft physically receives the signed document back from the customer/partner, similar to how an EIN rejection (also type: "other") is handled outside this endpoint — see the note below.
A scan-signature rejection closes the same way a file request does: upload the signed scan via the Upload order documents endpoint, passing this rejection's id as rejection_id.

{
    "id": 220901,
    "type": "scan-signature-request",
    "field": null,
    "reason": "Signature required for: Operating Agreement.",
    "message": "This document requires a scanned signature. To proceed with filing, download the document, print it, sign it, scan it, and upload the scanned document.",
    "instruction_document_url": "https://.../scan-signature-instructions.pdf",
    "instruction_document_uuid": "3e8a1d4c-7b2f-4c9e-a6d5-8f0b2e4c6a13",
    "template_document_url": "https://.../operating-agreement.pdf",
    "template_document_uuid": "c4d7e2a9-1f3b-4d6e-8a5c-7b9e0f2d4a68"
}

Neither signature type is answerable via the plain rejection-response endpoint below — submitting a text response against either one 422s.

Submit a rejection response

POST {baseUrl}/orders/{order_uuid}/rejection
Authorization: Bearer {token}
Content-Type: application/json

{
  "order_rejection_id": 220742,
  "field": "business_name",
  "response": "Bright Harbor Consulting LLC."
}

Field	Type	Notes
`order_uuid`	string (path)	UUID of the order you are tracking (the parent order for a bundle).
`order_rejection_id`	integer	The `id` from `required_actions.rejections`. Must belong to the order or one of its child lines.
`response`	string	Your reply that resolves the rejection. Max 255 characters.

Success

{
  "data": {
    "message": "Rejection response submitted successfully",
    "order_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "success": true
}

Recording the response closes the rejection: it no longer appears under required_actions.rejections. If ALL pending rejections have been settled the order's reported status moves from Action Required back to In Progress. A order_status_changed webhook is emitted for the order's new status.

📝 Note: EIN-specific rejections (the entry with error_code and id: null) are handled separately and are not answerable through this endpoint.

Errors and edge cases

422 Validation: order_rejection_id is missing/unknown, the rejection does not belong to this order (or its child lines), the rejection requires a document upload instead (a file request, a required-document rejection, or a scan-signature request — see the message table above), the rejection is a wet-signature request, the rejection has already been responded to, or response is empty or longer than 255 characters.
401 / 403: The order is not associated with your partner account.

Discovering open rejections​

Signature-required rejections​

Submit a rejection response​

Success​

Errors and edge cases​

Discovering open rejections

Signature-required rejections

Submit a rejection response

Success

Errors and edge cases