Foreign Qualification

Partners submit all required business and jurisdiction information when creating the order. Based on the entity type and state-specific requirements, additional information may be required to complete the filing.

Swyft evaluates each order and may request additional inputs during processing. Once all required information is received, Swyft completes the filing and returns status updates, confirmation details, and registration identifiers.

When to use this flow

Use the Foreign Qualification service when you are only filing for authority in a foreign state. If the customer is also forming a new entity, use the incorporation flow and add filings as guided by your SwyftFilings representative.

Service slug and catalog

Call Get Services and find the entry whose name / description corresponds to foreign qualification.
Use that item’s slug as the service path parameter for Get Service Configuration and as the service property on Create New Order.
The Get Service Configuration service will provide the list of Fields that needs to be included as information on the Payload, for a successful order creation.
Alongside the list of Fields, you will get a Cost Breakdown of the main service and those that are associated to the type of service requested.

The examples below use the slug foreign-qualification. Replace it with the slug returned for your account.

API flow

Step	Method	Endpoint
1. List Services (once per integration)	GET	`/service-carts`
2. Configuration, `input_fields`, catalog	GET	`/service-carts/{service}`
3. NAICS list (if required by `input_fields`)	GET	`/business-classifications`
4. Create order	POST	`/orders`
5. Poll order (optional)	GET	`/orders/{order_uuid}`
6. Get timely Order status changes and Requests for Information on your Webhook

Example: List services

GET {baseUrl}/service-carts
Authorization: Bearer {token}

{
  "success": true,
  "data": [
    {
      "slug": "foreign-qualification",
      "name": "Foreign Qualification",
      "description": "Service to file a foreign qualification",
      "allows_addons": false,
      "is_standalone": true,
      "nested_services": []
    }
  ]
}

State-specific requirements (discovery)

API-driven configuration: For each target state, call Get Service Configuration with your Foreign Qualification service slug and build the order using the returned input_fields and catalog.

input_fields return the complete list of required fields, types, and validation_rules for that state and product. Additional inputs may be required during processing based on jurisdiction-specific or filing-specific conditions.

Foreign Qualification uses a dedicated jurisdiction field

Unlike other products, Foreign Qualification's state-specific input_fields (and which optional add-on services are included) are gated by state_of_foreign_qualification — the state the FQ filing is being requested in — not by business_data.formation_state. Still send business_data.formation_state (the entity's home/formation state); it's required and stored on the order, but it no longer determines which fields this product requires. See State requirements reference.

pricing lists line items (Associated Child Services) with slug, name, price, optional stateFee by state, and customFees — an extensible array of additional state/service-specific surcharges (e.g. the Publication service's newspaper fee), each { key, name, amount }. customFees is [] when none apply.

Do not cache field keys across states without revalidating; states differ in officer lists, consent, and supporting documents.

Conditionally required fields

A field can be required only when another field's submitted value matches a specific answer, rather than always required or always optional. When this applies, its input_fields entry carries a conditional_required object (see State requirements reference for the general shape).

Example — Alaska "Alien Affiliates" disclosure: for Alaska orders, state_specific.has_alien_affiliates (a yes/no disclosure) is always required. The affiliate detail fields — alien_affiliates_data.*.name, .address, .city, .state, .zip — are required: false but carry:

{
  "field": "state_specific.has_alien_affiliates",
  "values": [true]
}

Submit alien_affiliates_data entries only if state_specific.has_alien_affiliates is true. If it's false, omit alien_affiliates_data entirely. Sending has_alien_affiliates: true without at least one affiliate entry returns a 422 naming the missing alien_affiliates_data.* fields.

Example — New York beneficial ownership disclosure: for state_of_foreign_qualification=NY, input_fields includes beneficial_ownership_disclosure (required) alongside the beneficial_owners_data.* fields (.name, .address, .city, .state, .zip, .address_complement, .unique_id_number, .id_document) directly on this cart's own schema — no separate lookup or nested-service order is needed. The owner detail fields carry:

{
  "field": "beneficial_ownership_disclosure",
  "values": ["reporting company"]
}

Submit beneficial_owners_data entries only when beneficial_ownership_disclosure is "reporting company". If the entity is claiming an exemption instead, set beneficial_ownership_disclosure to "exempt company" and provide state_specific.beneficial_ownership_exemption_type, whose conditional_required is gated on that same "exempt company" value.

Example: Get Service Configuration

Request (replace {baseUrl}, {token}, and the slug):

GET {baseUrl}/service-carts/foreign-qualification?state=TX&business_type=SCorp
Authorization: Bearer {token}

Abbreviated success payload:

{
	"data": {
		"name": "Foreign Qualification",
		"slug": "foreign-qualification",
		"description": "Service to file a foreign qualification",
		"allows_addons": false,
		"standalone": true,
		"input_fields": [
			{
                "name": "First Name",
                "key": "first_name",
                "type": "string",
                "description": "First name of the user",
                "questionnaire_copy": "What is your first name?",
                "validation_rules": [
                    "string",
                    "max:100",
                    "regex:/^[\\p{L}]+([\\s\\-'.]*[\\p{L}]+)*\\.?$/u"
                ],
                "default_value": null,
                "options": null,
                "is_sensitive": false,
                "required": true
            },
            {
                "name": "Last Name",
                "key": "last_name",
                "type": "string",
                "description": "Last name of the user",
                "questionnaire_copy": "What is your last name?",
                "validation_rules": [
                    "string",
                    "max:100",
                    "regex:/^[\\p{L}]+([\\s\\-'.]*[\\p{L}]+)*\\.?$/u"
                ],
                "default_value": null,
                "options": null,
                "is_sensitive": false,
                "required": true
            },
            {
                "name": "Email",
                "key": "email",
                "type": "string",
                "description": "Email address",
                "questionnaire_copy": "What is your email address?",
                "validation_rules": [
                    "email:rfc,dns",
                    "max:255"
                ],
                "default_value": null,
                "options": null,
                "is_sensitive": false,
                "required": true
            },
            {
                "name": "Phone Number",
                "key": "phone_number",
                "type": "string",
                "description": "Phone number",
                "questionnaire_copy": "What is your phone number?",
                "validation_rules": [
                    "string",
                    "size:10",
                    "regex:/^(?![01])\\d+$/"
                ],
                "default_value": null,
                "options": null,
                "is_sensitive": false,
                "required": true
            },
			...
		],
		"pricing": [
			{
				"slug": "foreign-qualification",
				"name": "Foreign Qualification",
				"price": 75,
				"stateFee": 750,
				"customFees": [],
				"is_parent": true
			},
			{
				"slug": "certificate-of-good-standing",
				"name": "Certificate of good standing",
				"price": 75,
				"stateFee": 15,
				"customFees": [],
				"is_parent": false
			},
			{
				"slug": "registered-agent",
				"name": "Registered Agent",
				"price": 75,
				"stateFee": 0,
				"customFees": [],
				"is_parent": false
			},
			{
				"slug": "publication",
				"name": "Publication",
				"price": 75,
				"stateFee": 0,
				"customFees": [
					{ "key": "newspaper_fee", "name": "Newspaper Fee", "amount": 100 }
				],
				"is_parent": false
			}
		]
	},
	"success": true
}

slug, stateFee, customFees, and field keys are illustrative; your environment returns the live catalog. The publication entry's customFees example above reflects a Nebraska (NE) order — the newspaper fee amount is state-specific.

Example: Create order

Request:

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

{
  "service": "foreign-qualification",
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Doe",
  "phone_number": "5551234567",
  "consent_sms": false,
  "state_of_foreign_qualification": "TX",
  "business_data": {
    "name": "Acme Holdings LLC",
    "type": "LLC",
    "formation_state": "DE",
    "category": "541211",
    "address": "100 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701"
  }
}

Registered agent included

In some configurations, Registered Agent service is included in the Foreign Qualification bundle with Swyft as the registered agent. On those cases, registered_agent details are optional — you do not need to send them. Provide a registered_agent object only if you are designating a different agent.

Jurisdiction: Set state_of_foreign_qualification to the state where the entity is seeking authority to operate — that's what drives this order's state-specific fields and add-on services. business_data.formation_state (and related address fields) is still required and stored as the entity's home state, but it plays no role in this product's state-gated logic.

Use the keys returned by Get Service Configuration to determine how state and jurisdiction fields should be populated for each order.

Abbreviated response:

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

Alternative, missing information:

If the initial validations fail, or there is missing information, you will get a 422 response such as this one from the API Create Order endpoint:

{
  "message": "The email field must be a valid email address. (and 2 more errors)",
  "errors": {
    "email": [
      "The email field must be a valid email address."
    ],
    "business_data.formation_date": [
      "The business_data.formation_date field is required."
    ],
    "business_data.category": [
      "The business_data.category field is required."
    ]
  }
}

Until all errors are cleared, the order will not be created.

Fulfillment

Order processing: After creation or submission, SwyftFilings evaluates the order and may request additional information required to complete the filing through an Information Request message via Webhook (See Webhooks).
Webhooks: Use order_status_change to track progress.
Completion: The order reaches a terminal success state when filings are accepted; documents are available to the Partner on the order evidence response payload.

Errors and edge cases

422 Validation: Field keys or values that fail validation_rules return errors keyed by field name.
Unsupported combinations: catalog may include conditions.must_not_be_added_with for incompatible products.
State/entity-type restriction: state_of_foreign_qualification=DE combined with business_data.type=Nonprofit is not offered for this service. Get Service Configuration (GET /service-carts/foreign-qualification?state=DE&business_type=Nonprofit) returns a 422, and POST /orders returns a 422 if attempted anyway.
Invalid query parameters: state must be a real two-letter US state code and business_type must be one of the accepted values; Get Service Configuration returns a 422 for either otherwise (e.g. state=XX or state=PR, a US territory not currently supported).

When to use this flow​

Service slug and catalog​

API flow​

Example: List services​

State-specific requirements (discovery)​

Conditionally required fields​

Example: Get Service Configuration​

Example: Create order​

Fulfillment​

Errors and edge cases​