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,
      "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.

This also applies to idempotent order creation (see the "Duplicate order" case on Create Order): if your account has an idempotency slot configured, the "state" half of the duplicate check is state_of_foreign_qualification for this service, not business_data.formation_state.

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. Each entry also carries recurrent (true when the service bills on a recurring cadence, e.g. Registered Agent, rather than a one-time purchase) and cadence_months (the billing cadence in months, e.g. 12 for annual — null when recurrent is false).
formation_state (required query parameter) is the entity's home/formation state — the same value you send as business_data.formation_state on the order. The Certificate of Good Standing and Certified Copy are issued by the home state, so their stateFee and customFees are priced in formation_state. Foreign Qualification itself and every other associated child service are priced in state (the state of foreign qualification). Your order is charged in the same states.

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&formation_state=DE&business_type=S%20Corporation
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,
				"state_fee": 750,
				"custom_fees": [],
				"is_parent": true,
				"recurrent": false,
				"cadence_months": null
			},
			{
				"slug": "certificate-of-good-standing",
				"name": "Certificate of good standing",
				"price": 75,
				"state_fee": 15,
				"custom_fees": [],
				"is_parent": false,
				"recurrent": false,
				"cadence_months": null
			},
			{
				"slug": "registered-agent",
				"name": "Registered Agent",
				"price": 75,
				"state_fee": 0,
				"custom_fees": [],
				"is_parent": false,
				"recurrent": true,
				"cadence_months": 12
			},
			{
				"slug": "publication",
				"name": "Publication",
				"price": 75,
				"state_fee": 0,
				"custom_fees": [
					{ "key": "newspaper_fee", "name": "Newspaper Fee", "amount": 100 }
				],
				"is_parent": false,
				"recurrent": false,
				"cadence_months": null
			}
		]
	},
	"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. The certificate-of-good-standing entry's stateFee is the formation_state fee, not the state fee.

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.

managers_data requirements

managers_data is validated against the following rules, keyed by entity type and the jurisdiction (state_of_foreign_qualification):

LLC — at least 1 record with title set to Member, plus at least 1 record with title set to Manager if business_data.managed_by is managers.
C Corporation and S Corporation — at least 1 record each with title set to Director, President, Treasurer, and Secretary.
Nonprofit — at least 1 Director, President, Treasurer, and Secretary in every state, plus at least 3 Director records in restricted states (AK, AL, AR, CT, FL, HI, ID, IL, IN, KY, ME, MI, MO, MT, ND, NE, NJ, NY, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, WV, WY).
LLC, S Corporation, C Corporation, and Nonprofit — at least 1 record with title set to Owner in AK, HI, AL, WA, TN, DE, and WV.
LLC — at least 1 record with title set to Governing Person in DC, ID, ND, TX, and WA.

This same rule set is documented in options.message on the managers_data field returned by Get Service Configuration.

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_changed to track progress.
Added services: SwyftFilings staff may add services (e.g. a DBA or a Certificate of Good Standing) to an existing Foreign Qualification order. Each addition fires the order_service_added webhook, and every service added this way is listed under additional_order_services (see Services added after the order).
Completion: The order reaches a terminal success state when filings are accepted; documents are available to the Partner on the order evidence response payload.

Services added after the order

GET {baseUrl}/orders/{order_uuid}, GET {baseUrl}/orders/search, and the order object of every webhook include additional_order_services: one entry per service SwyftFilings staff added to the order after it was created, in the same shape as the pricing entries from Get Service Configuration (is_parent is always false). Services that were part of the original order — the Foreign Qualification itself and the add-on services included for its state — are not listed. An added service that is later cancelled is removed from the list. The array is [] until staff add a service.

"additional_order_services": [
	{ "slug": "dba-filing", "name": "DBA Filing", "price": 75, "state_fee": 25, "custom_fees": [], "is_parent": false, "recurrent": false, "cadence_months": null },
	{ "slug": "certificate-of-good-standing", "name": "Certificate of good standing", "price": 75, "state_fee": 5, "custom_fees": [], "is_parent": false, "recurrent": false, "cadence_months": null }
]

Prices and fees come from the current catalog for the state and business type SwyftFilings staff selected when adding each service — which can differ from the order's state_of_foreign_qualification — not a record of amounts charged. If a service has no catalog entry, slug may be null, name is the service's display name, and price is null.

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 and formation_state must be real two-letter US state codes and business_type must be one of the accepted values; Get Service Configuration returns a 422 for any of them otherwise (e.g. state=XX or state=PR, a US territory not currently supported).
Missing formation_state: formation_state is required for this service; Get Service Configuration returns a 422 naming formation_state when it is omitted.

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​

managers_data requirements​

Fulfillment​

Services added after the order​

Errors and edge cases​