{ "openapi": "3.1.1", "info": { "version": "1.6.0", "title": "FileForms API Reference", "description": "See the full docs at https://docs.fileforms.com.", "contact": { "email": "info@fileforms.com", "url": "https://fileforms.com" } }, "servers": [ { "url": "https://api.fileforms.com/v1", "description": "Live server" }, { "url": "https://api.staging.fileforms.dev/v1", "description": "Test server" } ], "tags": [ { "name": "Authentication", "description": "Endpoints for managing authentication" }, { "name": "Users", "description": "Endpoints for managing users" }, { "name": "Companies", "description": "Endpoints for managing companies" }, { "name": "Orders", "description": "Endpoints for managing orders" }, { "name": "Documents", "description": "Endpoints for managing documents" }, { "name": "Organization", "description": "Endpoints for managing your organization settings and branding" }, { "name": "Prices", "description": "Endpoints for managing custom retail prices" }, { "name": "Webhook Endpoints", "description": "Endpoints for managing webhook endpoints" }, { "name": "Webhook Deliveries", "description": "Endpoints for inspecting and resending webhook deliveries" }, { "name": "Webhook Events", "description": "Events FileForms delivers to your webhook endpoints" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" }, "WebhookSignature": { "type": "apiKey", "in": "header", "name": "FileForms-Signature", "description": "Webhook signature in the format: t={timestamp},v1={signature}, where v1 is a hex-encoded HMAC-SHA256 of `{t}.{raw request body}` computed with your endpoint's `whsec_` signing secret. See https://docs.fileforms.com/guides/webhooks/setup-and-verification for the verification steps and a code example." } }, "schemas": { "CreateMagicLinkRequest": { "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "companyId": { "type": "string", "description": "Optional company ID to redirect the user to a specific company" } }, "required": [ "userId" ], "example": { "userId": "user_a1b2c3d4e5f6g7h8" } }, "MagicLinkResponse": { "type": "object", "properties": { "magicLink": { "type": "string", "format": "uri", "description": "URL including the authentication token. Expires after 7 days." } }, "required": [ "magicLink" ], "example": { "magicLink": "https://apps.fileforms.com/?token=1234567890" } }, "CreateUserRequest": { "type": "object", "properties": { "fullName": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" }, "phoneNumber": { "type": "string", "description": "Optional phone number in E.164 format" } }, "required": [ "fullName", "email" ], "example": { "fullName": "John Smith", "email": "john.smith@example.com", "phoneNumber": "+11234567890" } }, "UserResponse": { "type": "object", "properties": { "id": { "type": "string" }, "fullName": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phoneNumber": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "fullName", "email", "phoneNumber", "createdAt", "updatedAt" ], "example": { "id": "user_a1b2c3d4e5f6g7h8", "fullName": "John Smith", "email": "john.smith@example.com", "phoneNumber": "+11234567890", "createdAt": "2025-01-01T00:00:00Z", "updatedAt": "2025-01-01T00:00:00Z" } }, "CreateCompanyRequest": { "type": "object", "properties": { "legalName": { "type": "string", "minLength": 1 }, "tradeName": { "type": "string", "description": "Optional DBA (Doing Business As) name of the company" }, "ein": { "type": "string", "pattern": "^\\d{2}-\\d{7}$", "description": "Optional Employer Identification Number in the format XX-XXXXXXX" }, "entityType": { "type": "string", "enum": [ "LLC", "CORP" ] }, "structureType": { "type": "string", "enum": [ "MEMBER", "MANAGER" ], "description": "Required when entity type is LLC" }, "taxElection": { "type": "string", "enum": [ "C Corporation", "S Corporation" ], "description": "Required when entity type is CORP" }, "fiscalEndMonth": { "type": "string", "enum": [ "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December" ], "default": "December" }, "formationDate": { "type": "string", "format": "date", "description": "Date of initial filing in the state of formation" }, "formationState": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ], "description": "State the entity was originally formed in" }, "principalAddress": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "line2": { "type": "string", "minLength": 1, "description": "Address line 2, such as the apartment, suite, unit, or building." }, "city": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "state": { "type": "string", "minLength": 1, "description": "State, county, province, or region. Two-letter state code for US addresses; free text elsewhere." }, "postalCode": { "type": "string", "minLength": 1, "description": "ZIP or postal code. Five digits for US addresses; free text elsewhere." }, "country": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "description": "Two-letter country code (ISO 3166-1 alpha-2)." } }, "required": [ "line1", "city", "country" ] }, "mailingAddress": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "line2": { "type": "string", "minLength": 1, "description": "Address line 2, such as the apartment, suite, unit, or building." }, "city": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "state": { "type": "string", "minLength": 1, "description": "State, county, province, or region. Two-letter state code for US addresses; free text elsewhere." }, "postalCode": { "type": "string", "minLength": 1, "description": "ZIP or postal code. Five digits for US addresses; free text elsewhere." }, "country": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "description": "Two-letter country code (ISO 3166-1 alpha-2)." } }, "required": [ "line1", "city", "country" ] }, "officers": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COMPANY" ] }, "companyName": { "type": "string", "minLength": 1 }, "title": { "type": "string", "enum": [ "President", "Vice President", "Secretary", "Treasurer", "CEO", "CFO", "COO", "Managing Member", "Member", "Manager" ], "description": "If entity type is CORP, the title must be: President, Vice President, Secretary, Treasurer, CEO, CFO, or COO. If entity type is LLC, the title must be: Managing Member, Member, or Manager. At least one LLC officer must have a title of Member or Managing Member." }, "address": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "line2": { "type": "string", "minLength": 1, "description": "Address line 2, such as the apartment, suite, unit, or building." }, "city": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "state": { "type": "string", "minLength": 1, "description": "State, county, province, or region. Two-letter state code for US addresses; free text elsewhere." }, "postalCode": { "type": "string", "minLength": 1, "description": "ZIP or postal code. Five digits for US addresses; free text elsewhere." }, "country": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "description": "Two-letter country code (ISO 3166-1 alpha-2)." } }, "required": [ "line1", "city", "country" ] }, "isPrimary": { "type": "boolean", "description": "One officer must be the primary officer" } }, "required": [ "type", "companyName", "title", "address", "isPrimary" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PERSON" ] }, "firstName": { "type": "string", "minLength": 1 }, "lastName": { "type": "string", "minLength": 1 }, "title": { "type": "string", "enum": [ "President", "Vice President", "Secretary", "Treasurer", "CEO", "CFO", "COO", "Managing Member", "Member", "Manager" ], "description": "If entity type is CORP, the title must be: President, Vice President, Secretary, Treasurer, CEO, CFO, or COO. If entity type is LLC, the title must be: Managing Member, Member, or Manager. At least one LLC officer must have a title of Member or Managing Member." }, "address": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "line2": { "type": "string", "minLength": 1, "description": "Address line 2, such as the apartment, suite, unit, or building." }, "city": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "state": { "type": "string", "minLength": 1, "description": "State, county, province, or region. Two-letter state code for US addresses; free text elsewhere." }, "postalCode": { "type": "string", "minLength": 1, "description": "ZIP or postal code. Five digits for US addresses; free text elsewhere." }, "country": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "description": "Two-letter country code (ISO 3166-1 alpha-2)." } }, "required": [ "line1", "city", "country" ] }, "isPrimary": { "type": "boolean", "description": "One officer must be the primary officer" } }, "required": [ "type", "firstName", "lastName", "title", "address", "isPrimary" ] } ] }, "minItems": 1 }, "userId": { "type": "string", "minLength": 1 } }, "required": [ "legalName", "entityType", "formationDate", "formationState", "principalAddress", "mailingAddress", "officers", "userId" ], "example": { "userId": "user_a1b2c3d4e5f6g7h8", "legalName": "Acme LLC", "tradeName": "Acme", "ein": "12-3456789", "entityType": "LLC", "structureType": "MEMBER", "fiscalEndMonth": "September", "formationDate": "2025-01-01", "formationState": "TX", "principalAddress": { "line1": "123 Main Street", "line2": "Suite 100", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" }, "mailingAddress": { "line1": "123 Main Street", "line2": "Suite 100", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" }, "officers": [ { "type": "PERSON", "title": "Managing Member", "firstName": "John", "lastName": "Smith", "address": { "line1": "123 Main Street", "line2": "Suite 100", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" }, "isPrimary": true }, { "type": "COMPANY", "title": "Member", "companyName": "Globex Corp", "address": { "line1": "123 Main Street", "line2": "Suite 100", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" }, "isPrimary": false } ] } }, "UpdateCompanyRequest": { "type": "object", "properties": { "legalName": { "type": "string", "minLength": 1 }, "tradeName": { "type": "string", "description": "Optional DBA (Doing Business As) name of the company" }, "ein": { "type": "string", "pattern": "^\\d{2}-\\d{7}$", "description": "Optional Employer Identification Number in the format XX-XXXXXXX" }, "entityType": { "type": "string", "enum": [ "LLC", "CORP" ] }, "structureType": { "type": "string", "enum": [ "MEMBER", "MANAGER" ], "description": "Required when entity type is LLC" }, "taxElection": { "type": "string", "enum": [ "C Corporation", "S Corporation" ], "description": "Required when entity type is CORP" }, "fiscalEndMonth": { "type": "string", "enum": [ "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December" ], "default": "December" }, "formationDate": { "type": "string", "format": "date", "description": "Date of initial filing in the state of formation" }, "formationState": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ], "description": "State the entity was originally formed in" }, "principalAddress": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "line2": { "type": "string", "minLength": 1, "description": "Address line 2, such as the apartment, suite, unit, or building." }, "city": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "state": { "type": "string", "minLength": 1, "description": "State, county, province, or region. Two-letter state code for US addresses; free text elsewhere." }, "postalCode": { "type": "string", "minLength": 1, "description": "ZIP or postal code. Five digits for US addresses; free text elsewhere." }, "country": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "description": "Two-letter country code (ISO 3166-1 alpha-2)." } }, "required": [ "line1", "city", "country" ] }, "mailingAddress": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "line2": { "type": "string", "minLength": 1, "description": "Address line 2, such as the apartment, suite, unit, or building." }, "city": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "state": { "type": "string", "minLength": 1, "description": "State, county, province, or region. Two-letter state code for US addresses; free text elsewhere." }, "postalCode": { "type": "string", "minLength": 1, "description": "ZIP or postal code. Five digits for US addresses; free text elsewhere." }, "country": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "description": "Two-letter country code (ISO 3166-1 alpha-2)." } }, "required": [ "line1", "city", "country" ] }, "officers": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COMPANY" ] }, "companyName": { "type": "string", "minLength": 1 }, "title": { "type": "string", "enum": [ "President", "Vice President", "Secretary", "Treasurer", "CEO", "CFO", "COO", "Managing Member", "Member", "Manager" ], "description": "If entity type is CORP, the title must be: President, Vice President, Secretary, Treasurer, CEO, CFO, or COO. If entity type is LLC, the title must be: Managing Member, Member, or Manager. At least one LLC officer must have a title of Member or Managing Member." }, "address": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "line2": { "type": "string", "minLength": 1, "description": "Address line 2, such as the apartment, suite, unit, or building." }, "city": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "state": { "type": "string", "minLength": 1, "description": "State, county, province, or region. Two-letter state code for US addresses; free text elsewhere." }, "postalCode": { "type": "string", "minLength": 1, "description": "ZIP or postal code. Five digits for US addresses; free text elsewhere." }, "country": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "description": "Two-letter country code (ISO 3166-1 alpha-2)." } }, "required": [ "line1", "city", "country" ] }, "isPrimary": { "type": "boolean", "description": "One officer must be the primary officer" } }, "required": [ "type", "companyName", "title", "address", "isPrimary" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PERSON" ] }, "firstName": { "type": "string", "minLength": 1 }, "lastName": { "type": "string", "minLength": 1 }, "title": { "type": "string", "enum": [ "President", "Vice President", "Secretary", "Treasurer", "CEO", "CFO", "COO", "Managing Member", "Member", "Manager" ], "description": "If entity type is CORP, the title must be: President, Vice President, Secretary, Treasurer, CEO, CFO, or COO. If entity type is LLC, the title must be: Managing Member, Member, or Manager. At least one LLC officer must have a title of Member or Managing Member." }, "address": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "line2": { "type": "string", "minLength": 1, "description": "Address line 2, such as the apartment, suite, unit, or building." }, "city": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "state": { "type": "string", "minLength": 1, "description": "State, county, province, or region. Two-letter state code for US addresses; free text elsewhere." }, "postalCode": { "type": "string", "minLength": 1, "description": "ZIP or postal code. Five digits for US addresses; free text elsewhere." }, "country": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "description": "Two-letter country code (ISO 3166-1 alpha-2)." } }, "required": [ "line1", "city", "country" ] }, "isPrimary": { "type": "boolean", "description": "One officer must be the primary officer" } }, "required": [ "type", "firstName", "lastName", "title", "address", "isPrimary" ] } ] }, "minItems": 1 } }, "example": { "legalName": "Acme LLC", "tradeName": "Acme", "ein": "12-3456789", "entityType": "LLC", "structureType": "MEMBER", "fiscalEndMonth": "September", "formationDate": "2025-01-01", "formationState": "TX", "principalAddress": { "line1": "123 Main Street", "line2": "Suite 100", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" }, "mailingAddress": { "line1": "123 Main Street", "line2": "Suite 100", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" }, "officers": [ { "type": "PERSON", "title": "Managing Member", "firstName": "John", "lastName": "Smith", "address": { "line1": "123 Main Street", "line2": "Suite 100", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" }, "isPrimary": true }, { "type": "COMPANY", "title": "Member", "companyName": "Globex Corp", "address": { "line1": "123 Main Street", "line2": "Suite 100", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" }, "isPrimary": false } ] } }, "CompanyResponse": { "type": "object", "properties": { "id": { "type": "string" }, "legalName": { "type": "string" }, "tradeName": { "type": [ "string", "null" ] }, "ein": { "type": [ "string", "null" ], "pattern": "^\\d{2}-\\d{7}$" }, "entityType": { "type": "string", "enum": [ "LLC", "CORP" ] }, "structureType": { "type": [ "string", "null" ], "enum": [ "MEMBER", "MANAGER", null ] }, "taxElection": { "type": [ "string", "null" ], "enum": [ "C Corporation", "S Corporation", null ] }, "fiscalEndMonth": { "type": "string", "enum": [ "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December" ] }, "formationDate": { "type": "string", "format": "date" }, "formationState": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ] }, "principalAddress": { "type": [ "object", "null" ], "properties": { "line1": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "line2": { "type": [ "string", "null" ], "minLength": 1, "description": "Address line 2, such as the apartment, suite, unit, or building." }, "city": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "state": { "type": [ "string", "null" ], "minLength": 1, "description": "State, county, province, or region. Two-letter state code for US addresses; free text elsewhere." }, "postalCode": { "type": [ "string", "null" ], "minLength": 1, "description": "ZIP or postal code. Five digits for US addresses; free text elsewhere." }, "country": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "description": "Two-letter country code (ISO 3166-1 alpha-2)." } }, "required": [ "line1", "line2", "city", "state", "postalCode", "country" ] }, "mailingAddress": { "type": [ "object", "null" ], "properties": { "line1": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "line2": { "type": [ "string", "null" ], "minLength": 1, "description": "Address line 2, such as the apartment, suite, unit, or building." }, "city": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "state": { "type": [ "string", "null" ], "minLength": 1, "description": "State, county, province, or region. Two-letter state code for US addresses; free text elsewhere." }, "postalCode": { "type": [ "string", "null" ], "minLength": 1, "description": "ZIP or postal code. Five digits for US addresses; free text elsewhere." }, "country": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "description": "Two-letter country code (ISO 3166-1 alpha-2)." } }, "required": [ "line1", "line2", "city", "state", "postalCode", "country" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "legalName", "tradeName", "ein", "entityType", "structureType", "taxElection", "fiscalEndMonth", "formationDate", "formationState", "principalAddress", "mailingAddress", "createdAt", "updatedAt" ], "example": { "id": "comp_a1b2c3d4e5f6g7h8", "legalName": "Acme LLC", "tradeName": "Acme", "ein": "12-3456789", "entityType": "LLC", "structureType": "MEMBER", "fiscalEndMonth": "September", "formationDate": "2025-01-01", "formationState": "TX", "principalAddress": { "line1": "123 Main Street", "line2": "Suite 100", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" }, "mailingAddress": { "line1": "123 Main Street", "line2": "Suite 100", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" }, "createdAt": "2025-01-01T00:00:00Z", "updatedAt": "2025-01-01T00:00:00Z" } }, "CreateOrderRequest": { "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "companyId": { "type": "string", "minLength": 1, "description": "Required when formation service is not included" }, "filingState": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ], "description": "State for the filing(s)" }, "formation": { "type": "object", "properties": { "company": { "type": "object", "properties": { "legalName": { "type": "string", "minLength": 1 }, "entityType": { "type": "string", "enum": [ "LLC", "CORP" ] }, "structureType": { "type": "string", "enum": [ "MEMBER", "MANAGER" ], "description": "Required when entity type is LLC" }, "taxElection": { "type": "string", "enum": [ "C Corporation", "S Corporation" ], "description": "Required when entity type is CORP" }, "fiscalEndMonth": { "type": "string", "enum": [ "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December" ], "default": "December" }, "principalAddress": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "line2": { "type": "string", "minLength": 1, "description": "Address line 2, such as the apartment, suite, unit, or building." }, "city": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "state": { "type": "string", "minLength": 1, "description": "State, county, province, or region. Two-letter state code for US addresses; free text elsewhere." }, "postalCode": { "type": "string", "minLength": 1, "description": "ZIP or postal code. Five digits for US addresses; free text elsewhere." }, "country": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "description": "Two-letter country code (ISO 3166-1 alpha-2)." } }, "required": [ "line1", "city", "country" ] }, "mailingAddress": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "line2": { "type": "string", "minLength": 1, "description": "Address line 2, such as the apartment, suite, unit, or building." }, "city": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "state": { "type": "string", "minLength": 1, "description": "State, county, province, or region. Two-letter state code for US addresses; free text elsewhere." }, "postalCode": { "type": "string", "minLength": 1, "description": "ZIP or postal code. Five digits for US addresses; free text elsewhere." }, "country": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "description": "Two-letter country code (ISO 3166-1 alpha-2)." } }, "required": [ "line1", "city", "country" ] }, "officers": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COMPANY" ] }, "companyName": { "type": "string", "minLength": 1 }, "title": { "type": "string", "enum": [ "President", "Vice President", "Secretary", "Treasurer", "CEO", "CFO", "COO", "Managing Member", "Member", "Manager" ], "description": "If entity type is CORP, the title must be: President, Vice President, Secretary, Treasurer, CEO, CFO, or COO. If entity type is LLC, the title must be: Managing Member, Member, or Manager. At least one LLC officer must have a title of Member or Managing Member." }, "address": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "line2": { "type": "string", "minLength": 1, "description": "Address line 2, such as the apartment, suite, unit, or building." }, "city": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "state": { "type": "string", "minLength": 1, "description": "State, county, province, or region. Two-letter state code for US addresses; free text elsewhere." }, "postalCode": { "type": "string", "minLength": 1, "description": "ZIP or postal code. Five digits for US addresses; free text elsewhere." }, "country": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "description": "Two-letter country code (ISO 3166-1 alpha-2)." } }, "required": [ "line1", "city", "country" ] }, "isPrimary": { "type": "boolean", "description": "One officer must be the primary officer" } }, "required": [ "type", "companyName", "title", "address", "isPrimary" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PERSON" ] }, "firstName": { "type": "string", "minLength": 1 }, "lastName": { "type": "string", "minLength": 1 }, "title": { "type": "string", "enum": [ "President", "Vice President", "Secretary", "Treasurer", "CEO", "CFO", "COO", "Managing Member", "Member", "Manager" ], "description": "If entity type is CORP, the title must be: President, Vice President, Secretary, Treasurer, CEO, CFO, or COO. If entity type is LLC, the title must be: Managing Member, Member, or Manager. At least one LLC officer must have a title of Member or Managing Member." }, "address": { "type": "object", "properties": { "line1": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "line2": { "type": "string", "minLength": 1, "description": "Address line 2, such as the apartment, suite, unit, or building." }, "city": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "state": { "type": "string", "minLength": 1, "description": "State, county, province, or region. Two-letter state code for US addresses; free text elsewhere." }, "postalCode": { "type": "string", "minLength": 1, "description": "ZIP or postal code. Five digits for US addresses; free text elsewhere." }, "country": { "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "description": "Two-letter country code (ISO 3166-1 alpha-2)." } }, "required": [ "line1", "city", "country" ] }, "isPrimary": { "type": "boolean", "description": "One officer must be the primary officer" } }, "required": [ "type", "firstName", "lastName", "title", "address", "isPrimary" ] } ] }, "minItems": 1 } }, "required": [ "legalName", "entityType", "principalAddress", "mailingAddress", "officers" ] }, "alternativeNames": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "maxItems": 10, "default": [], "description": "Optional alternative entity names, in order of preference, used if the state rejects the primary legal name. Each name must be non-empty. Defaults to an empty list." }, "registeredAgent": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COMPANY" ] }, "companyName": { "type": "string", "minLength": 1 }, "addressStreet": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "addressCity": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "addressState": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ] }, "addressZip": { "type": "string", "pattern": "^\\d{5}$" } }, "required": [ "type", "companyName", "addressStreet", "addressCity", "addressState", "addressZip" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PERSON" ] }, "firstName": { "type": "string", "minLength": 1 }, "lastName": { "type": "string", "minLength": 1 }, "addressStreet": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "addressCity": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "addressState": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ] }, "addressZip": { "type": "string", "pattern": "^\\d{5}$" } }, "required": [ "type", "firstName", "lastName", "addressStreet", "addressCity", "addressState", "addressZip" ] } ], "description": "Required when registered agent service is not included" }, "expedited": { "type": "boolean", "default": false, "description": "Optional expedited formation service. Only available for: Arizona (LLC), Delaware (LLC), Florida (LLC), Nevada (LLC), New York (LLC), Wyoming (LLC)." } }, "required": [ "company" ], "description": "Form a new entity" }, "ein": { "type": "object", "properties": { "businessCategory": { "type": "string", "enum": [ "Accommodations", "Construction", "Consulting", "Finance", "Food Services", "Health Care", "Insurance", "Manufacturing", "Organization", "Real Estate", "Rental & Leasing", "Repair", "Retail", "Sell Goods", "Service", "Social Assistance", "Transportation", "Warehousing", "Wholesale", "Other" ], "description": "Select the option that best describes the category of your business." }, "businessPurpose": { "type": "string", "minLength": 1, "description": "Indicate principal line of merchandise sold, specific construction work done, products produced, or services provided." }, "applicationReason": { "type": "string", "enum": [ "Started a new business", "Hired employee(s)", "Banking purposes", "Changed type of organization", "Purchased active business" ], "description": "Why are you requesting an EIN?" }, "vehicle55kPounds": { "type": "boolean", "description": "Does your business own a motor vehicle with a taxable gross vehicle weight of 55,000 pounds or more?" }, "gamblingWagering": { "type": "boolean", "description": "Does your business involve gambling/wagering?" }, "fileForm720": { "type": "boolean", "description": "Does your business need to file Form 720 (Quarterly Federal Excise Tax Return)?" }, "alcoholTobaccoFirearms": { "type": "boolean", "description": "Does your business sell or manufacture alcohol, tobacco, or firearms?" }, "isW2Expected": { "type": "boolean", "description": "Do you have, or do you expect to have, any employees who will receive Forms W-2 in the next 12 months?" }, "agricultureEmployeesCount": { "type": "integer", "minimum": 0, "description": "Highest number of agricultural employees expected in the next 12 months. When isW2Expected true, the sum of agricultureEmployeesCount and otherEmployeesCount must be greater than 0." }, "otherEmployeesCount": { "type": "integer", "minimum": 0, "description": "Highest number of non-agricultural employees expected in the next 12 months. When isW2Expected true, the sum of agricultureEmployeesCount and otherEmployeesCount must be greater than 0." }, "firstWagesDate": { "type": [ "string", "null" ], "format": "date", "description": "First date wages or annuities were or will be paid. If applicant is a withholding agent, enter date income will first be paid to nonresident alien. Required when isW2Expected true." }, "fileForm944": { "type": "boolean", "description": "If you expect your employment tax liability to be $1,000 or less in a full calendar year, do you want to file Form 944 annually instead of Forms 941 quarterly?" }, "responsiblePartyFirstName": { "type": "string", "minLength": 1, "description": "First name of the person responsible for the EIN request." }, "responsiblePartyLastName": { "type": "string", "minLength": 1, "description": "Last name of the person responsible for the EIN request." }, "responsiblePartyTitle": { "type": "string", "minLength": 1, "description": "Title of the person responsible for the EIN request." }, "responsiblePartyIsForeign": { "type": "boolean", "default": false, "description": "Whether the responsible party is a foreign person. When true, an SSN is not required." }, "responsiblePartySsn": { "type": "string", "pattern": "^\\d{9}$", "description": "Social security number of the person responsible for the EIN request. Required unless responsiblePartyIsForeign is true." }, "responsiblePartyPhoneNumber": { "type": "string", "description": "Phone number of the person responsible for the EIN request, in E.164 format." } }, "required": [ "businessCategory", "businessPurpose", "applicationReason", "vehicle55kPounds", "gamblingWagering", "fileForm720", "alcoholTobaccoFirearms", "isW2Expected", "agricultureEmployeesCount", "otherEmployeesCount", "firstWagesDate", "fileForm944", "responsiblePartyFirstName", "responsiblePartyLastName", "responsiblePartyTitle", "responsiblePartyPhoneNumber" ], "description": "Request an EIN" }, "annualReport": { "type": "object", "properties": { "filingYear": { "type": "string", "pattern": "^\\d{4}$", "description": "Filing year for the annual report" }, "registeredAgent": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COMPANY" ] }, "companyName": { "type": "string", "minLength": 1 }, "addressStreet": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "addressCity": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "addressState": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ] }, "addressZip": { "type": "string", "pattern": "^\\d{5}$" } }, "required": [ "type", "companyName", "addressStreet", "addressCity", "addressState", "addressZip" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PERSON" ] }, "firstName": { "type": "string", "minLength": 1 }, "lastName": { "type": "string", "minLength": 1 }, "addressStreet": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "addressCity": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "addressState": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ] }, "addressZip": { "type": "string", "pattern": "^\\d{5}$" } }, "required": [ "type", "firstName", "lastName", "addressStreet", "addressCity", "addressState", "addressZip" ] } ], "description": "Required when registered agent service is not included and there is no active registered agent service for the filing state" } }, "required": [ "filingYear" ], "description": "File an annual report" }, "foreignQualification": { "anyOf": [ { "type": "object", "properties": { "registeredAgent": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COMPANY" ] }, "companyName": { "type": "string", "minLength": 1 }, "addressStreet": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "addressCity": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "addressState": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ] }, "addressZip": { "type": "string", "pattern": "^\\d{5}$" } }, "required": [ "type", "companyName", "addressStreet", "addressCity", "addressState", "addressZip" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PERSON" ] }, "firstName": { "type": "string", "minLength": 1 }, "lastName": { "type": "string", "minLength": 1 }, "addressStreet": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "addressCity": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "addressState": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ] }, "addressZip": { "type": "string", "pattern": "^\\d{5}$" } }, "required": [ "type", "firstName", "lastName", "addressStreet", "addressCity", "addressState", "addressZip" ] } ], "description": "Required when registered agent service is not included and there is no active registered agent service for the filing state" } } }, { "type": "boolean", "enum": [ true ] } ], "description": "Register your entity to do business in another state" }, "registeredAgent": { "type": "object", "properties": { "isChangeOfAgent": { "type": "boolean", "description": "Whether this is a change of agent or new agent" } }, "required": [ "isChangeOfAgent" ], "description": "Request a registered agent" } }, "required": [ "userId", "filingState" ], "example": { "userId": "user_a1b2c3d4e5f6g7h8", "companyId": "comp_a1b2c3d4e5f6g7h8", "filingState": "TX", "annualReport": { "filingYear": "2025" }, "registeredAgent": { "isChangeOfAgent": true } } }, "OrderResponse": { "type": "object", "properties": { "companyId": { "type": "string" }, "items": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "orderType": { "type": "string", "enum": [ "formation", "ein", "foreign_qualification" ] }, "orderId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "filingDate": { "type": [ "string", "null" ], "format": "date-time" }, "filingStatus": { "type": "string", "enum": [ "submitted", "pending", "filed", "exception", "cancelled" ] }, "subscriptionStatus": { "type": "null" } }, "required": [ "orderType", "orderId", "createdAt", "filingDate", "filingStatus", "subscriptionStatus" ] }, { "type": "object", "properties": { "orderType": { "type": "string", "enum": [ "annual_report" ] }, "orderId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "filingDate": { "type": [ "string", "null" ], "format": "date-time" }, "filingStatus": { "type": "string", "enum": [ "submitted", "pending", "filed", "exception", "cancelled" ] }, "subscriptionStatus": { "type": "string", "enum": [ "active", "canceled", "past_due" ] } }, "required": [ "orderType", "orderId", "createdAt", "filingDate", "filingStatus", "subscriptionStatus" ] }, { "type": "object", "properties": { "orderType": { "type": "string", "enum": [ "registered_agent" ] }, "filingType": { "type": "string", "enum": [ "change_of_agent" ], "description": "Type of registered agent filing (e.g. change_of_agent)" }, "orderId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "filingDate": { "type": [ "string", "null" ], "format": "date-time" }, "filingStatus": { "type": "string", "enum": [ "submitted", "pending", "filed", "exception", "cancelled" ] }, "subscriptionStatus": { "type": "string", "enum": [ "active", "canceled", "past_due" ] }, "registeredAgent": { "type": "object", "properties": { "companyName": { "type": "string" }, "street": { "type": "string", "minLength": 1, "description": "Address line 1, such as the street, PO Box, or company name." }, "city": { "type": "string", "minLength": 1, "description": "City, district, suburb, town, or village." }, "state": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ] }, "zip": { "type": "string", "pattern": "^\\d{5}$" } }, "required": [ "companyName", "street", "city", "state", "zip" ] } }, "required": [ "orderType", "orderId", "createdAt", "filingDate", "filingStatus", "subscriptionStatus", "registeredAgent" ] } ] } } }, "required": [ "companyId", "items" ], "example": { "companyId": "comp_a1b2c3d4e5f6g7h8", "items": [ { "orderType": "annual_report", "orderId": "order_a1b2c3d4e5f6g7h8", "createdAt": "2025-01-01T00:00:00Z", "filingDate": null, "filingStatus": "submitted", "subscriptionStatus": "active" }, { "orderType": "registered_agent", "orderId": "order_a1b2c3d4e5f6g7h9", "createdAt": "2025-01-01T00:00:00Z", "filingDate": null, "filingStatus": "submitted", "subscriptionStatus": "active", "registeredAgent": { "companyName": "Corporate Creations Network Inc.", "street": "5444 Westheimer #1000", "city": "Houston", "state": "TX", "zip": "77056" } } ] } }, "DocumentResponse": { "type": "object", "properties": { "documentId": { "type": "string" }, "documentType": { "type": "string", "enum": [ "company", "registered_agent", "articles_of_organization", "certificate_of_good_standing", "annual_report", "ein", "change_of_agent", "articles_of_incorporation", "foreign_qualification" ] }, "fileName": { "type": "string" }, "fileType": { "type": "string", "description": "MIME file type" }, "fileUrl": { "type": "string", "format": "uri", "description": "URL for downloading the file. Expires after 1 hour." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "documentId", "documentType", "fileName", "fileType", "fileUrl", "createdAt" ], "example": { "documentId": "doc_a1b2c3d4e5f6g7h8", "documentType": "registered_agent", "fileName": "document.pdf", "fileType": "application/pdf", "fileUrl": "https://bucket.s3.us-east-1.amazonaws.com/document.pdf?X-Amz-Signature=...", "createdAt": "2025-01-01T00:00:00Z" } }, "DocumentUploadedEvent": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "document.uploaded" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "orderId": { "type": "string" }, "documentId": { "type": "string" }, "documentType": { "type": "string", "enum": [ "company", "registered_agent", "articles_of_organization", "certificate_of_good_standing", "annual_report", "ein", "change_of_agent", "articles_of_incorporation", "foreign_qualification" ] }, "fileName": { "type": "string" }, "fileType": { "type": "string", "description": "MIME file type" }, "fileUrl": { "type": "string", "format": "uri", "description": "URL for downloading the file. Expires after 1 hour." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "orderId", "documentId", "documentType", "fileName", "fileType", "fileUrl", "createdAt" ] } }, "required": [ "id", "type", "createdAt", "data" ], "example": { "id": "evt_a1b2c3d4e5f6g7h8", "type": "document.uploaded", "createdAt": "2025-01-01T00:00:00Z", "data": { "orderId": "order_a1b2c3d4e5f6g7h8", "documentId": "doc_a1b2c3d4e5f6g7h8", "documentType": "registered_agent", "fileName": "document.pdf", "fileType": "application/pdf", "fileUrl": "https://bucket.s3.us-east-1.amazonaws.com/document.pdf?X-Amz-Signature=...", "createdAt": "2025-01-01T00:00:00Z" } } }, "FilingStatusChangedEvent": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "filing.status_changed" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "oneOf": [ { "type": "object", "properties": { "orderType": { "type": "string", "enum": [ "formation", "ein", "foreign_qualification" ] }, "orderId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "filingDate": { "type": [ "string", "null" ], "format": "date-time" }, "filingStatus": { "type": "string", "enum": [ "submitted", "pending", "filed", "exception", "cancelled" ] }, "subscriptionStatus": { "type": "null" }, "exceptionCode": { "type": [ "string", "null" ], "enum": [ "460", "461", "462", "463", "464", "465", "466", "467", "468", "469", "470", "471", "472", "473", "474", "481", "482", "483", "484", "486", "487", "489", "492", "493", "494", "495", "496", "497", "498", "499", null ] }, "exceptionReason": { "type": [ "string", "null" ], "enum": [ "Payment required. Client hasn't submitted payment", "Payment exception. Expired or invalid credit card", "Missing required data", "Entity naming exception", "Entity name rejected", "Entity name not available", "Bad or missing entity address", "Bad or missing mailing address", "Bad or missing primary contact information", "Bad or missing RA information", "Bad or missing filing detail data. Ancillary filing data (principal business activity, etc.)", "Bad or missing governance", "Bad or missing ownership or stock data", "Bad or missing jurisdiction specific data", "Bad or missing entity type data required for filing", "Filing rejected by jurisdiction. The jurisdiction has rejected the filing for an unknown reason", "Annual report prerequisite exception. A previous year AR error exists that is preventing filing the current year's AR", "EIN SSN rejected", "EIN SSN does not match person's name", "Bad or Missing NAICS Code", "Out of State RA", "Invalid Principle Address (PMB, etc.)", "COA - Compliance Needed", "Entity administratively dissolved", "Missing environment variable needed for filing", "Entity not found: No matching record for name and type", "Missing or invalid State Document Number", "Authentication failure with jurisdiction", "Annual report is not required this year", "Failed to submit order through API", null ] }, "exceptionMessage": { "type": [ "string", "null" ] } }, "required": [ "orderType", "orderId", "createdAt", "filingDate", "filingStatus", "subscriptionStatus", "exceptionCode", "exceptionReason", "exceptionMessage" ] }, { "type": "object", "properties": { "orderType": { "type": "string", "enum": [ "annual_report" ] }, "orderId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "filingDate": { "type": [ "string", "null" ], "format": "date-time" }, "filingStatus": { "type": "string", "enum": [ "submitted", "pending", "filed", "exception", "cancelled" ] }, "subscriptionStatus": { "type": "string", "enum": [ "active", "canceled", "past_due" ] }, "exceptionCode": { "type": [ "string", "null" ], "enum": [ "460", "461", "462", "463", "464", "465", "466", "467", "468", "469", "470", "471", "472", "473", "474", "481", "482", "483", "484", "486", "487", "489", "492", "493", "494", "495", "496", "497", "498", "499", null ] }, "exceptionReason": { "type": [ "string", "null" ], "enum": [ "Payment required. Client hasn't submitted payment", "Payment exception. Expired or invalid credit card", "Missing required data", "Entity naming exception", "Entity name rejected", "Entity name not available", "Bad or missing entity address", "Bad or missing mailing address", "Bad or missing primary contact information", "Bad or missing RA information", "Bad or missing filing detail data. Ancillary filing data (principal business activity, etc.)", "Bad or missing governance", "Bad or missing ownership or stock data", "Bad or missing jurisdiction specific data", "Bad or missing entity type data required for filing", "Filing rejected by jurisdiction. The jurisdiction has rejected the filing for an unknown reason", "Annual report prerequisite exception. A previous year AR error exists that is preventing filing the current year's AR", "EIN SSN rejected", "EIN SSN does not match person's name", "Bad or Missing NAICS Code", "Out of State RA", "Invalid Principle Address (PMB, etc.)", "COA - Compliance Needed", "Entity administratively dissolved", "Missing environment variable needed for filing", "Entity not found: No matching record for name and type", "Missing or invalid State Document Number", "Authentication failure with jurisdiction", "Annual report is not required this year", "Failed to submit order through API", null ] }, "exceptionMessage": { "type": [ "string", "null" ] } }, "required": [ "orderType", "orderId", "createdAt", "filingDate", "filingStatus", "subscriptionStatus", "exceptionCode", "exceptionReason", "exceptionMessage" ] }, { "type": "object", "properties": { "orderType": { "type": "string", "enum": [ "registered_agent" ] }, "filingType": { "type": "string", "enum": [ "change_of_agent" ], "description": "Type of registered agent filing (e.g. change_of_agent)" }, "orderId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "filingDate": { "type": [ "string", "null" ], "format": "date-time" }, "filingStatus": { "type": "string", "enum": [ "submitted", "pending", "filed", "exception", "cancelled" ] }, "subscriptionStatus": { "type": "string", "enum": [ "active", "canceled", "past_due" ] }, "exceptionCode": { "type": [ "string", "null" ], "enum": [ "460", "461", "462", "463", "464", "465", "466", "467", "468", "469", "470", "471", "472", "473", "474", "481", "482", "483", "484", "486", "487", "489", "492", "493", "494", "495", "496", "497", "498", "499", null ] }, "exceptionReason": { "type": [ "string", "null" ], "enum": [ "Payment required. Client hasn't submitted payment", "Payment exception. Expired or invalid credit card", "Missing required data", "Entity naming exception", "Entity name rejected", "Entity name not available", "Bad or missing entity address", "Bad or missing mailing address", "Bad or missing primary contact information", "Bad or missing RA information", "Bad or missing filing detail data. Ancillary filing data (principal business activity, etc.)", "Bad or missing governance", "Bad or missing ownership or stock data", "Bad or missing jurisdiction specific data", "Bad or missing entity type data required for filing", "Filing rejected by jurisdiction. The jurisdiction has rejected the filing for an unknown reason", "Annual report prerequisite exception. A previous year AR error exists that is preventing filing the current year's AR", "EIN SSN rejected", "EIN SSN does not match person's name", "Bad or Missing NAICS Code", "Out of State RA", "Invalid Principle Address (PMB, etc.)", "COA - Compliance Needed", "Entity administratively dissolved", "Missing environment variable needed for filing", "Entity not found: No matching record for name and type", "Missing or invalid State Document Number", "Authentication failure with jurisdiction", "Annual report is not required this year", "Failed to submit order through API", null ] }, "exceptionMessage": { "type": [ "string", "null" ] } }, "required": [ "orderType", "orderId", "createdAt", "filingDate", "filingStatus", "subscriptionStatus", "exceptionCode", "exceptionReason", "exceptionMessage" ] } ] } }, "required": [ "id", "type", "createdAt", "data" ], "example": { "id": "evt_a1b2c3d4e5f6g7h8", "type": "filing.status_changed", "createdAt": "2025-01-01T00:00:00Z", "data": { "orderType": "annual_report", "orderId": "order_a1b2c3d4e5f6g7h8", "createdAt": "2025-01-01T00:00:00Z", "filingDate": null, "filingStatus": "submitted", "subscriptionStatus": "active", "exceptionCode": null, "exceptionReason": null, "exceptionMessage": null } } }, "WebhookResponse": { "type": "object", "properties": { "received": { "type": "boolean" } }, "required": [ "received" ], "example": { "received": true } }, "OrganizationResponse": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "subdomain": { "type": [ "string", "null" ], "description": "Set when the domain is an org subdomain of fileforms.com" }, "logoUrl": { "type": [ "string", "null" ] }, "iconUrl": { "type": [ "string", "null" ] }, "primaryColor": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$" }, "primaryTextColor": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$" }, "surfaceColor": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$" }, "surfaceTextColor": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$" }, "replyToEmail": { "type": [ "string", "null" ] }, "websiteUrl": { "type": [ "string", "null" ] }, "billedUsers": { "type": [ "string", "null" ], "enum": [ "admin", "all", null ] }, "invoicedEnabled": { "type": "boolean", "description": "True once billing is onboarded; gates API keys and org-billed ordering" }, "showPrices": { "type": "boolean" }, "signupDisabled": { "type": "boolean", "description": "Disable self-serve signup on this domain" }, "signupKeys": { "type": "array", "items": { "type": "string" }, "description": "Signups require one of these keys when non-empty" }, "supportChatEnabled": { "type": "boolean", "description": "Show the FileForms support chat widget to this organization’s users" }, "notifications": { "type": "object", "properties": { "documentUploadedEmail": { "type": "boolean", "default": true, "description": "Email users when a filed document is available" }, "filingStatusEmail": { "type": "boolean", "default": true, "description": "Email users when a filing status changes" }, "annualReportReminderEmail": { "type": "boolean", "default": true, "description": "Email users about upcoming annual report deadlines" }, "paymentCompletedEmail": { "type": "boolean", "default": true, "description": "Email the purchasing user a receipt when their payment completes" } } }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "name", "domain", "subdomain", "logoUrl", "iconUrl", "primaryColor", "primaryTextColor", "surfaceColor", "surfaceTextColor", "replyToEmail", "websiteUrl", "billedUsers", "invoicedEnabled", "showPrices", "signupDisabled", "signupKeys", "supportChatEnabled", "notifications", "createdAt" ], "example": { "name": "Acme Advisors", "domain": "acme.fileforms.com", "subdomain": "acme", "logoUrl": "https://assets.fileforms.com/organizations/42/logo-a1b2c3d4.png", "iconUrl": "https://assets.fileforms.com/organizations/42/icon-a1b2c3d4.png", "primaryColor": "#18A37A", "primaryTextColor": "#FAFAFA", "surfaceColor": "#0E2B3D", "surfaceTextColor": "#FAFAFA", "replyToEmail": "support@acmeadvisors.com", "websiteUrl": "https://acmeadvisors.com", "billedUsers": null, "invoicedEnabled": false, "showPrices": true, "signupDisabled": false, "signupKeys": [], "supportChatEnabled": true, "notifications": { "documentUploadedEmail": true, "filingStatusEmail": true, "annualReportReminderEmail": true, "paymentCompletedEmail": true }, "createdAt": "2025-01-01T00:00:00Z" } }, "UpdateOrganizationRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "primaryColor": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$" }, "primaryTextColor": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$" }, "surfaceColor": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$" }, "surfaceTextColor": { "type": [ "string", "null" ], "pattern": "^#[0-9a-fA-F]{6}$" }, "replyToEmail": { "type": [ "string", "null" ], "format": "email" }, "websiteUrl": { "type": [ "string", "null" ], "format": "uri" }, "billedUsers": { "type": [ "string", "null" ], "enum": [ "admin", "all", null ], "description": "Whose orders the organization pays for; requires billing to be onboarded" }, "showPrices": { "type": "boolean" }, "signupDisabled": { "type": "boolean", "description": "Disable self-serve signup on this domain" }, "signupKeys": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Signups require one of these keys when non-empty; empty array removes the gate" }, "supportChatEnabled": { "type": "boolean", "description": "Show the FileForms support chat widget to this organization’s users" }, "notifications": { "type": "object", "properties": { "documentUploadedEmail": { "type": "boolean", "default": true, "description": "Email users when a filed document is available" }, "filingStatusEmail": { "type": "boolean", "default": true, "description": "Email users when a filing status changes" }, "annualReportReminderEmail": { "type": "boolean", "default": true, "description": "Email users about upcoming annual report deadlines" }, "paymentCompletedEmail": { "type": "boolean", "default": true, "description": "Email the purchasing user a receipt when their payment completes" } } } }, "example": { "name": "Acme Advisors", "primaryColor": "#18A37A", "replyToEmail": "support@acmeadvisors.com", "notifications": { "annualReportReminderEmail": false } } }, "UploadBrandingAssetRequest": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "logo", "icon" ] }, "fileType": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp" ], "description": "MIME type of the image" }, "file": { "type": "string", "description": "Base64-encoded image data" } }, "required": [ "kind", "fileType", "file" ], "example": { "kind": "logo", "fileType": "image/png", "file": "iVBORw0KGgoAAAANSUhEUgAA..." } }, "UploadBrandingAssetResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ], "example": { "url": "https://assets.fileforms.com/organizations/42/logo-a1b2c3d4.png" } }, "PricesResponse": { "type": "object", "properties": { "prices": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ein", "expedited_formation", "formation_tier_1", "formation_tier_2", "formation_tier_3", "annual_report", "registered_agent", "foreign_qualification", "certificate_of_good_standing" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ], "description": "Pricing footnote — what the price includes and what is added on top at checkout" }, "defaultAmount": { "type": "integer", "description": "FileForms list price in dollars, used when no custom price is set" }, "retailAmount": { "type": [ "integer", "null" ], "description": "Custom price in dollars users pay, when set" }, "wholesaleAmount": { "type": "integer", "description": "Amount in dollars FileForms collects; the retail floor" }, "enabled": { "type": "boolean", "description": "Whether the product is offered for purchase; only formation tiers can be disabled" } }, "required": [ "type", "name", "description", "defaultAmount", "retailAmount", "wholesaleAmount", "enabled" ] } } }, "required": [ "prices" ], "example": { "prices": [ { "type": "annual_report", "name": "Annual Report", "description": "Billed as an annual subscription.", "defaultAmount": 149, "retailAmount": 129, "wholesaleAmount": 99, "enabled": true }, { "type": "registered_agent", "name": "Registered Agent", "description": "Billed as an annual subscription. Also added at checkout with Formation Tier 2 and 3.", "defaultAmount": 149, "retailAmount": null, "wholesaleAmount": 99, "enabled": true } ] } }, "UpsertPriceRequest": { "type": "object", "properties": { "retailAmount": { "type": "integer", "exclusiveMinimum": 0, "description": "Price in dollars users pay; must be at least the effective wholesale amount" }, "enabled": { "type": "boolean", "description": "Offer this product for purchase. Only formation tiers can be disabled; at least one must stay enabled." } }, "example": { "retailAmount": 129, "enabled": true } }, "PriceResponse": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ein", "expedited_formation", "formation_tier_1", "formation_tier_2", "formation_tier_3", "annual_report", "registered_agent", "foreign_qualification", "certificate_of_good_standing" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ], "description": "Pricing footnote — what the price includes and what is added on top at checkout" }, "defaultAmount": { "type": "integer", "description": "FileForms list price in dollars, used when no custom price is set" }, "retailAmount": { "type": [ "integer", "null" ], "description": "Custom price in dollars users pay, when set" }, "wholesaleAmount": { "type": "integer", "description": "Amount in dollars FileForms collects; the retail floor" }, "enabled": { "type": "boolean", "description": "Whether the product is offered for purchase; only formation tiers can be disabled" } }, "required": [ "type", "name", "description", "defaultAmount", "retailAmount", "wholesaleAmount", "enabled" ], "example": { "type": "annual_report", "name": "Annual Report", "description": "Billed as an annual subscription.", "defaultAmount": 149, "retailAmount": 129, "wholesaleAmount": 99, "enabled": true } }, "WebhookEndpointsResponse": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "document.uploaded", "filing.status_changed" ] } }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "eventTypes", "createdAt" ] } } }, "required": [ "endpoints" ], "example": { "endpoints": [ { "id": "we_a1b2c3d4e5f6g7h8", "url": "https://example.com/webhooks/fileforms", "eventTypes": [ "document.uploaded", "filing.status_changed" ], "createdAt": "2025-01-01T00:00:00Z" } ] } }, "CreateWebhookEndpointRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "document.uploaded", "filing.status_changed" ] }, "minItems": 1 } }, "required": [ "url", "eventTypes" ], "example": { "url": "https://example.com/webhooks/fileforms", "eventTypes": [ "document.uploaded", "filing.status_changed" ] } }, "WebhookEndpointCreatedResponse": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "document.uploaded", "filing.status_changed" ] } }, "createdAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "description": "Signing secret, returned only on creation" } }, "required": [ "id", "url", "eventTypes", "createdAt", "secret" ], "example": { "id": "we_a1b2c3d4e5f6g7h8", "url": "https://example.com/webhooks/fileforms", "eventTypes": [ "document.uploaded", "filing.status_changed" ], "createdAt": "2025-01-01T00:00:00Z", "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" } }, "UpdateWebhookEndpointRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "document.uploaded", "filing.status_changed" ] }, "minItems": 1 } }, "example": { "eventTypes": [ "document.uploaded" ] } }, "WebhookEndpointResponse": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "document.uploaded", "filing.status_changed" ] } }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "eventTypes", "createdAt" ], "example": { "id": "we_a1b2c3d4e5f6g7h8", "url": "https://example.com/webhooks/fileforms", "eventTypes": [ "document.uploaded", "filing.status_changed" ], "createdAt": "2025-01-01T00:00:00Z" } }, "WebhookDeliveriesResponse": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "endpoint": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "url" ], "description": "The endpoint this delivery targets" }, "type": { "type": "string", "enum": [ "document.uploaded", "filing.status_changed" ] }, "status": { "type": "string", "enum": [ "delivered", "pending", "failed" ], "description": "delivered; pending (automatic retries remain); failed (retries exhausted)" }, "attempts": { "type": "integer" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "nextAttemptAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the next automatic retry is due" }, "lastAttemptAt": { "type": [ "string", "null" ], "format": "date-time" }, "responseStatus": { "type": [ "integer", "null" ], "description": "HTTP status of the last attempt; null when no response was received" }, "responseError": { "type": [ "string", "null" ], "description": "Error from the last failed attempt, truncated" }, "data": { "description": "The event payload" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "endpoint", "type", "status", "attempts", "deliveredAt", "nextAttemptAt", "lastAttemptAt", "responseStatus", "responseError", "createdAt" ] } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as cursor to fetch the next page; null when there are no more" } }, "required": [ "deliveries", "nextCursor" ], "example": { "deliveries": [ { "id": "evt_a1b2c3d4e5f6g7h8", "endpoint": { "id": "we_a1b2c3d4e5f6g7h8", "url": "https://example.com/webhooks/fileforms" }, "type": "document.uploaded", "status": "delivered", "attempts": 1, "deliveredAt": "2025-01-01T00:00:05Z", "nextAttemptAt": null, "lastAttemptAt": "2025-01-01T00:00:05Z", "responseStatus": 200, "responseError": null, "data": { "orderId": "order_a1b2c3d4e5f6g7h8", "documentId": "doc_a1b2c3d4e5f6g7h8", "documentType": "registered_agent", "fileName": "document.pdf", "fileType": "application/pdf", "fileUrl": "https://bucket.s3.us-east-1.amazonaws.com/document.pdf?X-Amz-Signature=...", "createdAt": "2025-01-01T00:00:00Z" }, "createdAt": "2025-01-01T00:00:00Z" }, { "id": "evt_b2c3d4e5f6g7h8i9", "endpoint": { "id": "we_a1b2c3d4e5f6g7h8", "url": "https://example.com/webhooks/fileforms" }, "type": "filing.status_changed", "status": "failed", "attempts": 7, "deliveredAt": null, "nextAttemptAt": null, "lastAttemptAt": "2025-01-02T03:35:00Z", "responseStatus": 500, "responseError": "Internal Server Error", "data": { "orderType": "annual_report", "orderId": "order_a1b2c3d4e5f6g7h8", "createdAt": "2025-01-01T00:00:00Z", "filingDate": null, "filingStatus": "submitted", "subscriptionStatus": "active", "exceptionCode": null, "exceptionReason": null, "exceptionMessage": null }, "createdAt": "2025-01-01T00:00:00Z" } ], "nextCursor": "eyJ2IjoxLCJrIjoiY3JlYXRlZEF0IiwibyI6ImRlc2MiLCJzIjoxNzU0OTUwNDAwMDAwLCJpZCI6ImV2dF9iMmMzZDRlNWY2ZzdoOGk5In0" } }, "ResendWebhookDeliveriesRequest": { "type": "object", "properties": { "eventIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 100, "description": "Event IDs to resend, at most 100" } }, "required": [ "eventIds" ], "example": { "eventIds": [ "evt_a1b2c3d4e5f6g7h8", "evt_b2c3d4e5f6g7h8i9" ] } }, "ResendWebhookDeliveriesResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "delivered": { "type": "boolean" }, "responseStatus": { "type": [ "integer", "null" ] }, "responseError": { "type": [ "string", "null" ] } }, "required": [ "id", "delivered", "responseStatus", "responseError" ] } } }, "required": [ "results" ], "example": { "results": [ { "id": "evt_a1b2c3d4e5f6g7h8", "delivered": true, "responseStatus": 200, "responseError": null }, { "id": "evt_b2c3d4e5f6g7h8i9", "delivered": false, "responseStatus": 500, "responseError": "Internal Server Error" } ] } }, "RetryFailedWebhooksResponse": { "type": "object", "properties": { "queued": { "type": "integer", "description": "Failed events re-queued for the next automatic retry sweep" } }, "required": [ "queued" ], "example": { "queued": 3 } }, "SendTestWebhookRequest": { "type": "object", "properties": { "eventType": { "type": "string", "enum": [ "document.uploaded", "filing.status_changed" ] } }, "required": [ "eventType" ], "example": { "eventType": "document.uploaded" } }, "TestWebhookResponse": { "type": "object", "properties": { "delivered": { "type": "boolean", "description": "True when the endpoint acknowledged the test event with a 2xx response" }, "eventId": { "type": [ "string", "null" ], "description": "Id of the test event, also shown in deliveries" } }, "required": [ "delivered", "eventId" ], "example": { "delivered": true, "eventId": "evt_a1b2c3d4e5f6g7h8" } } }, "parameters": {} }, "paths": { "/auth/magic-link": { "post": { "operationId": "createMagicLink", "summary": "Create Magic Link", "description": "Create a magic link to authenticate a user.", "tags": [ "Authentication" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMagicLinkRequest" } } } }, "responses": { "200": { "description": "Magic link created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MagicLinkResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Zod error code" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "JSON path to the invalid field; numeric segments are array indexes" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "path", "message" ] } } }, "required": [ "message", "errors" ] }, "example": { "message": "Invalid request", "errors": [ { "code": "invalid_type", "path": [ "userId" ], "message": "User ID is required" } ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "User not found" } } } } } } }, "/users/{userIdOrEmail}": { "get": { "operationId": "getUser", "summary": "Get User", "description": "Retrieve a user.", "tags": [ "Users" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "User ID or email", "example": "user_a1b2c3d4e5f6g7h8" }, "required": true, "description": "User ID or email", "name": "userIdOrEmail", "in": "path" } ], "responses": { "200": { "description": "User retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "User not found" } } } } } } }, "/users": { "post": { "operationId": "createUser", "summary": "Create User", "description": "Create a new user.", "tags": [ "Users" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserRequest" } } } }, "responses": { "200": { "description": "User created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Zod error code" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "JSON path to the invalid field; numeric segments are array indexes" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "path", "message" ] } } }, "required": [ "message", "errors" ] }, "example": { "message": "Invalid request", "errors": [ { "code": "invalid_type", "path": [ "email" ], "message": "Invalid email address" } ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } }, "409": { "description": "Email or phone number already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Email already exists" } } } } } } }, "/companies/{companyIdOrSlug}": { "get": { "operationId": "getCompany", "summary": "Get Company", "description": "Retrieve a company.", "tags": [ "Companies" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Company ID or slug", "example": "comp_a1b2c3d4e5f6g7h8" }, "required": true, "description": "Company ID or slug", "name": "companyIdOrSlug", "in": "path" } ], "responses": { "200": { "description": "Company retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Company not found" } } } } } }, "patch": { "operationId": "updateCompany", "summary": "Update Company", "description": "Update a company.", "tags": [ "Companies" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Company ID or slug", "example": "comp_a1b2c3d4e5f6g7h8" }, "required": true, "description": "Company ID or slug", "name": "companyIdOrSlug", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCompanyRequest" } } } }, "responses": { "200": { "description": "Company updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Zod error code" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "JSON path to the invalid field; numeric segments are array indexes" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "path", "message" ] } } }, "required": [ "message", "errors" ] }, "example": { "message": "Invalid request", "errors": [ { "code": "invalid_value", "path": [ "entityType" ], "message": "Invalid entity type" } ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Company not found" } } } }, "409": { "description": "EIN already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "EIN already exists" } } } } } } }, "/companies": { "post": { "operationId": "createCompany", "summary": "Create Company", "description": "Create a new company.", "tags": [ "Companies" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCompanyRequest" } } } }, "responses": { "200": { "description": "Company created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Zod error code" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "JSON path to the invalid field; numeric segments are array indexes" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "path", "message" ] } } }, "required": [ "message", "errors" ] }, "example": { "message": "Invalid request", "errors": [ { "code": "invalid_type", "path": [ "structureType" ], "message": "Structure type is required when entity type is LLC" } ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "User not found" } } } }, "409": { "description": "EIN already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "EIN already exists" } } } } } } }, "/orders": { "post": { "operationId": "createOrder", "summary": "Create Order", "description": "Order formation, annual report, and registered agent services.", "tags": [ "Orders" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" }, "examples": { "formation-with-ein": { "summary": "Formation with EIN and registered agent", "description": "Forms a new LLC with an EIN and FileForms registered agent service. Formation + EIN in one order is billed as the tier 2 bundle.", "value": { "userId": "user_a1b2c3d4e5f6g7h8", "filingState": "TX", "formation": { "expedited": false, "company": { "legalName": "Acme Holdings LLC", "entityType": "LLC", "structureType": "MEMBER", "principalAddress": { "line1": "123 Main Street", "line2": "Suite 100", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" }, "mailingAddress": { "line1": "123 Main Street", "line2": "Suite 100", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" }, "officers": [ { "type": "PERSON", "firstName": "Jane", "lastName": "Doe", "title": "Managing Member", "isPrimary": true, "address": { "line1": "123 Main Street", "line2": "Suite 100", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" } } ] } }, "ein": { "businessCategory": "Consulting", "businessPurpose": "Management consulting services", "applicationReason": "Started a new business", "vehicle55kPounds": false, "gamblingWagering": false, "fileForm720": false, "alcoholTobaccoFirearms": false, "isW2Expected": true, "agricultureEmployeesCount": 0, "otherEmployeesCount": 3, "firstWagesDate": "2026-09-01", "fileForm944": false, "responsiblePartyFirstName": "Jane", "responsiblePartyLastName": "Doe", "responsiblePartyTitle": "Managing Member", "responsiblePartySsn": "123456789", "responsiblePartyPhoneNumber": "7135550123" }, "registeredAgent": { "isChangeOfAgent": false } } }, "formation-expedited": { "summary": "Expedited formation", "description": "Expedited filing is available for LLCs in states with an expedited fee (see the expedited field description). Billed as tier 1 when no EIN is included.", "value": { "userId": "user_a1b2c3d4e5f6g7h8", "filingState": "DE", "formation": { "expedited": true, "company": { "legalName": "Acme Ventures LLC", "entityType": "LLC", "structureType": "MEMBER", "principalAddress": { "line1": "123 Main Street", "line2": "Suite 100", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" }, "mailingAddress": { "line1": "123 Main Street", "line2": "Suite 100", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" }, "officers": [ { "type": "PERSON", "firstName": "Jane", "lastName": "Doe", "title": "Managing Member", "isPrimary": true, "address": { "line1": "123 Main Street", "line2": "Suite 100", "city": "Houston", "state": "TX", "postalCode": "77002", "country": "US" } } ] } }, "registeredAgent": { "isChangeOfAgent": false } } }, "ein-standalone": { "summary": "EIN for an existing company", "description": "Obtains an EIN for a company that already exists. Billed at the standalone EIN price.", "value": { "userId": "user_a1b2c3d4e5f6g7h8", "companyId": "comp_x1y2z3w4v5u6t7s8", "filingState": "TX", "ein": { "businessCategory": "Consulting", "businessPurpose": "Management consulting services", "applicationReason": "Started a new business", "vehicle55kPounds": false, "gamblingWagering": false, "fileForm720": false, "alcoholTobaccoFirearms": false, "isW2Expected": true, "agricultureEmployeesCount": 0, "otherEmployeesCount": 3, "firstWagesDate": "2026-09-01", "fileForm944": false, "responsiblePartyFirstName": "Jane", "responsiblePartyLastName": "Doe", "responsiblePartyTitle": "Managing Member", "responsiblePartySsn": "123456789", "responsiblePartyPhoneNumber": "7135550123" } } }, "registered-agent": { "summary": "Change of registered agent", "description": "Replaces the company's current agent with FileForms registered agent service.", "value": { "userId": "user_a1b2c3d4e5f6g7h8", "companyId": "comp_x1y2z3w4v5u6t7s8", "filingState": "TX", "registeredAgent": { "isChangeOfAgent": true } } }, "foreign-qualification": { "summary": "Foreign qualification", "description": "Registers an existing company to do business in another state. Requires a registered agent in the qualifying state.", "value": { "userId": "user_a1b2c3d4e5f6g7h8", "companyId": "comp_x1y2z3w4v5u6t7s8", "filingState": "CA", "foreignQualification": true, "registeredAgent": { "isChangeOfAgent": false } } }, "annual-report": { "summary": "Annual report", "description": "Files the annual report for an existing company. The filing state must have a registered agent on record — order RA service alongside, or supply the existing agent in annualReport.registeredAgent.", "value": { "userId": "user_a1b2c3d4e5f6g7h8", "companyId": "comp_x1y2z3w4v5u6t7s8", "filingState": "FL", "annualReport": { "filingYear": "2026" }, "registeredAgent": { "isChangeOfAgent": false } } } } } } }, "responses": { "200": { "description": "Order created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Zod error code" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "JSON path to the invalid field; numeric segments are array indexes" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "path", "message" ] } } }, "required": [ "message", "errors" ] }, "example": { "message": "Invalid request", "errors": [ { "code": "invalid_value", "path": [ "filingState" ], "message": "Invalid state code" } ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } }, "402": { "description": "Insufficient prepaid balance — the automatic top-up could not complete, and the order was not placed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "balance": { "type": "integer", "description": "The organization's current prepaid balance, in cents" }, "required": { "type": "integer", "description": "The total the order needed to debit, in cents" } }, "required": [ "message", "balance", "required" ] }, "example": { "message": "Insufficient organization balance for this order. Top up your balance in Settings → Billing to place new orders.", "balance": 12500, "required": 32400 } } } }, "403": { "description": "Billing has not been set up for organization-billed ordering", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Set up billing to place organization-billed orders. An organization admin can complete billing setup in Settings → Billing." } } } } } } }, "/documents/{documentId}": { "get": { "operationId": "getDocument", "summary": "Get Document", "description": "Retrieve a document.", "tags": [ "Documents" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Document ID", "example": "doc_a1b2c3d4e5f6g7h8" }, "required": true, "description": "Document ID", "name": "documentId", "in": "path" } ], "responses": { "200": { "description": "Document retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Document not found" } } } } } } }, "/organization": { "get": { "operationId": "getOrganization", "summary": "Get Organization", "description": "Retrieve your organization settings.", "tags": [ "Organization" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Organization retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } } } }, "patch": { "operationId": "updateOrganization", "summary": "Update Organization", "description": "Update your organization settings. All fields are optional; only the provided fields are updated. Setting `billedUsers` requires billing to be onboarded.", "tags": [ "Organization" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationRequest" } } } }, "responses": { "200": { "description": "Organization updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Zod error code" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "JSON path to the invalid field; numeric segments are array indexes" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "path", "message" ] } } }, "required": [ "message", "errors" ] }, "example": { "message": "Invalid request", "errors": [ { "code": "invalid_format", "path": [ "primaryColor" ], "message": "Must be a 6-digit hex color like #18A37A" } ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Billing has not been onboarded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Set up billing before enabling organization-billed ordering." } } } } } } }, "/organization/branding/assets": { "post": { "operationId": "uploadBrandingAsset", "summary": "Upload Branding Asset", "description": "Upload a logo or icon as a base64-encoded image (png, jpeg, or webp; max 2MB). The file content must match the declared type. The uploaded asset immediately replaces the current logo or icon.", "tags": [ "Organization" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadBrandingAssetRequest" } } } }, "responses": { "200": { "description": "Branding asset uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadBrandingAssetResponse" } } } }, "400": { "description": "Invalid request body or file too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "File exceeds the 2MB limit" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } } } } }, "/organization/prices": { "get": { "operationId": "listPrices", "summary": "List Prices", "description": "List prices for all product types, including the FileForms default retail price, your custom retail price when set, and the wholesale floor. State filing fees are charged at cost in addition to all product prices; per-product composition notes (bundled EIN/DBA, the registered agent subscription added with Tier 2/3, the expedited surcharge) are in each row’s `description`.", "tags": [ "Prices" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Prices retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricesResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } } } } }, "/organization/prices/{type}": { "put": { "operationId": "setPrice", "summary": "Set Price", "description": "Set a custom retail price for a product type, or enable/disable a formation tier. `retailAmount` is in dollars and must be at least the wholesale floor: the per-product wholesale override when one exists, otherwise the product's default wholesale price. Floor violations include a `minimumAmount` field (dollars) alongside the error message. `enabled: false` is accepted for formation tiers only, and at least one tier must remain enabled.", "tags": [ "Prices" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "ein", "expedited_formation", "formation_tier_1", "formation_tier_2", "formation_tier_3", "annual_report", "registered_agent", "foreign_qualification", "certificate_of_good_standing" ], "description": "Product type", "example": "annual_report" }, "required": true, "description": "Product type", "name": "type", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertPriceRequest" } } } }, "responses": { "200": { "description": "Price set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceResponse" } } } }, "400": { "description": "Invalid request body or price below the wholesale floor", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Price must be at least $99. Contact FileForms about bulk credit purchasing to lower your wholesale rates." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } }, "404": { "description": "Unknown product type", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unknown product type" } } } } } }, "delete": { "operationId": "removePrice", "summary": "Remove Price", "description": "Remove the custom retail price for a product type. The FileForms default retail price applies afterwards.", "tags": [ "Prices" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "ein", "expedited_formation", "formation_tier_1", "formation_tier_2", "formation_tier_3", "annual_report", "registered_agent", "foreign_qualification", "certificate_of_good_standing" ], "description": "Product type", "example": "annual_report" }, "required": true, "description": "Product type", "name": "type", "in": "path" } ], "responses": { "200": { "description": "Custom price removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Custom price removed" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } }, "404": { "description": "Unknown product type or no custom price set", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "No custom price for this product" } } } } } } }, "/webhook-endpoints": { "get": { "operationId": "listWebhookEndpoints", "summary": "List Webhook Endpoints", "description": "List your webhook endpoints.", "tags": [ "Webhook Endpoints" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Webhook endpoints retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointsResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } } } }, "post": { "operationId": "createWebhookEndpoint", "summary": "Create Webhook Endpoint", "description": "Create a webhook endpoint. The signing secret is returned only in this response; store it securely to verify webhook signatures.", "tags": [ "Webhook Endpoints" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointRequest" } } } }, "responses": { "200": { "description": "Webhook endpoint created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreatedResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Zod error code" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "JSON path to the invalid field; numeric segments are array indexes" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "path", "message" ] } } }, "required": [ "message", "errors" ] }, "example": { "message": "Invalid request", "errors": [ { "code": "invalid_format", "path": [ "url" ], "message": "Webhook URLs must use https" } ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } } } } }, "/webhook-endpoints/{id}": { "patch": { "operationId": "updateWebhookEndpoint", "summary": "Update Webhook Endpoint", "description": "Update a webhook endpoint. All fields are optional; only the provided fields are updated.", "tags": [ "Webhook Endpoints" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Webhook endpoint ID (we_...)", "example": "we_a1b2c3d4e5f6g7h8" }, "required": true, "description": "Webhook endpoint ID (we_...)", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpointRequest" } } } }, "responses": { "200": { "description": "Webhook endpoint updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Zod error code" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "JSON path to the invalid field; numeric segments are array indexes" }, "message": { "type": "string", "description": "Human-readable error message" } }, "required": [ "code", "path", "message" ] } } }, "required": [ "message", "errors" ] }, "example": { "message": "Invalid request", "errors": [ { "code": "too_small", "path": [ "eventTypes" ], "message": "Too small: expected array to have >=1 items" } ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } }, "404": { "description": "Webhook endpoint not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Webhook endpoint not found" } } } } } }, "delete": { "operationId": "deleteWebhookEndpoint", "summary": "Delete Webhook Endpoint", "description": "Delete a webhook endpoint. Events are no longer delivered to it.", "tags": [ "Webhook Endpoints" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Webhook endpoint ID (we_...)", "example": "we_a1b2c3d4e5f6g7h8" }, "required": true, "description": "Webhook endpoint ID (we_...)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Webhook endpoint deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Webhook endpoint deleted" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } }, "404": { "description": "Webhook endpoint not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Webhook endpoint not found" } } } } } } }, "/webhook-endpoints/{id}/retry-failed": { "post": { "operationId": "retryFailedDeliveries", "summary": "Retry Failed Deliveries", "description": "Re-queue every failed delivery of the endpoint for the next automatic retry sweep (runs every few minutes). Retried events keep their original `id` and payload, so consumers must deduplicate on the event `id`.", "tags": [ "Webhook Endpoints" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Webhook endpoint ID (we_...)", "example": "we_a1b2c3d4e5f6g7h8" }, "required": true, "description": "Webhook endpoint ID (we_...)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Retries attempted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryFailedWebhooksResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } }, "404": { "description": "Webhook endpoint not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Webhook endpoint not found" } } } } } } }, "/webhook-endpoints/{id}/test": { "post": { "operationId": "sendTestEvent", "summary": "Send Test Event", "description": "Send a test event to a webhook endpoint. The endpoint must be subscribed to the requested event type.", "tags": [ "Webhook Endpoints" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Webhook endpoint ID (we_...)", "example": "we_a1b2c3d4e5f6g7h8" }, "required": true, "description": "Webhook endpoint ID (we_...)", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendTestWebhookRequest" } } } }, "responses": { "200": { "description": "Test webhook sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestWebhookResponse" } } } }, "400": { "description": "Invalid request body or endpoint not subscribed to the event type", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "This endpoint is not subscribed to that event type" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } }, "404": { "description": "Webhook endpoint not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Webhook endpoint not found" } } } } } } }, "/webhook-deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "List Webhook Deliveries", "description": "List webhook deliveries across all of your endpoints, newest first. A delivery is one event sent to one endpoint — an event fanned out to multiple subscribed endpoints appears once per endpoint, each with its own `id`. Filter by `endpoint`, event `type`, created `from`/`to` range, or delivery `status`: `delivered` (the endpoint acknowledged with a 2xx), `pending` (automatic retries remain), or `failed` (retries exhausted). Filters accept multiple comma-separated values, matching any of them. Paginate by passing `nextCursor` from the previous page as `cursor` — cursors are opaque; pass them back verbatim, and restart from the first page whenever you change any other parameter. To resume a sync without a stored cursor, pass your last-processed delivery's `createdAt` as `from` with `order=asc` and skip ids you have already seen.", "tags": [ "Webhook Deliveries" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Only deliveries to these webhook endpoints (comma-separated)", "example": "we_a1b2c3d4e5f6g7h8" }, "required": false, "description": "Only deliveries to these webhook endpoints (comma-separated)", "name": "endpoint", "in": "query" }, { "schema": { "type": "string", "description": "Filter by delivery status (comma-separated for any-of)", "example": "failed,pending" }, "required": false, "description": "Filter by delivery status (comma-separated for any-of)", "name": "status", "in": "query" }, { "schema": { "type": "string", "description": "Filter by event type (comma-separated for any-of)", "example": "document.uploaded" }, "required": false, "description": "Filter by event type (comma-separated for any-of)", "name": "type", "in": "query" }, { "schema": { "type": [ "string", "null" ], "format": "date-time", "description": "Only deliveries created at or after this time (ISO 8601)", "example": "2025-01-01T00:00:00Z" }, "required": false, "description": "Only deliveries created at or after this time (ISO 8601)", "name": "from", "in": "query" }, { "schema": { "type": [ "string", "null" ], "format": "date-time", "description": "Only deliveries created at or before this time (ISO 8601)", "example": "2025-02-01T00:00:00Z" }, "required": false, "description": "Only deliveries created at or before this time (ISO 8601)", "name": "to", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort by creation time", "example": "desc" }, "required": false, "description": "Sort by creation time", "name": "order", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Page size (1-100)", "example": 10 }, "required": false, "description": "Page size (1-100)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque pagination cursor; pass `nextCursor` from the previous page back verbatim", "example": "eyJ2IjoxLCJrIjoiY3JlYXRlZEF0IiwibyI6ImRlc2MiLCJzIjoxNzU0OTUwNDAwMDAwLCJpZCI6ImV2dF9iMmMzZDRlNWY2ZzdoOGk5In0" }, "required": false, "description": "Opaque pagination cursor; pass `nextCursor` from the previous page back verbatim", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Webhook deliveries retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveriesResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } }, "404": { "description": "Webhook endpoint not found (when the `endpoint` filter does not match one of yours)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Webhook endpoint not found" } } } } } } }, "/webhook-deliveries/resend": { "post": { "operationId": "resendWebhookDeliveries", "summary": "Resend Webhook Deliveries", "description": "Make one immediate delivery attempt for each of 1-100 events, returning a per-item outcome (unknown ids report as failed items rather than failing the batch). Resends deliver the SAME events — same `id` and payload, with fresh signature timestamps — so consumers must deduplicate on the event `id`. Works for any event, including already-delivered ones; automatic retries are not restarted or consumed. To retry every failed delivery of an endpoint instead, use Retry Failed Deliveries.", "tags": [ "Webhook Deliveries" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendWebhookDeliveriesRequest" } } } }, "responses": { "200": { "description": "Resends attempted; inspect per-item outcomes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendWebhookDeliveriesResponse" } } } }, "400": { "description": "Invalid request body (empty or more than 100 event ids)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Invalid request" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Unauthorized" } } } } } } } }, "webhooks": { "document.uploaded": { "post": { "summary": "Document Uploaded", "description": "Triggered when a document is uploaded and available for download. Deliveries are signed with the `FileForms-Signature` header and retried automatically on failure; see the [webhook guides](https://docs.fileforms.com/guides/webhooks/setup-and-verification) for delivery, retry, and signature verification.", "tags": [ "Webhook Events" ], "security": [ { "WebhookSignature": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUploadedEvent" } } } }, "responses": { "200": { "description": "Webhook event received", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } } } } }, "filing.status_changed": { "post": { "summary": "Filing Status Changed", "description": "Triggered when the status of a filing changes. Deliveries are signed with the `FileForms-Signature` header and retried automatically on failure; see the [webhook guides](https://docs.fileforms.com/guides/webhooks/setup-and-verification) for delivery, retry, and signature verification.", "tags": [ "Webhook Events" ], "security": [ { "WebhookSignature": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingStatusChangedEvent" } } } }, "responses": { "200": { "description": "Webhook event received", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } } } } } } }