> ## Documentation Index > Fetch the complete documentation index at: https://docs.symmetry.com/llms.txt > Use this file to discover all available pages before exploring further. # Return applicable guided flows for given home and work addresses > Returns applicable flows for the specified home and work address, used to filter the list of all applicable forms down to a list of required forms. ## OpenAPI ````yaml /spf/api-reference/payroll-forms-api.yaml post /guided-flows openapi: 3.0.1 info: title: SPF Api contact: name: Symmetry Software url: https://www.symmetry.com email: support@symmetry.com license: name: Symmetry Software/Subscription & Service Agreement url: http://www.symmetry.com/software-subscription-license version: 1.94.0 x-release-name: value: 2026.7.1 x-endpoint-versions: fill_pdf_post_version: 1.95.0 forms_version: 1.95.0 form_questions_version: 1.95.0 docs_version: 1.93.0 guided_flows_version: 1.95.0 flow_questions_version: 1.95.0 getPdf_version: 1.95.0 ste_mapping_version: 1.1.0 fill_pdf_get_version: 1.95.0 /v2/forms_version: 1.95.0 form_ids_version: 1.95.0 form_catalog_version: 1.87.0 servers: - url: https://api.symmetry.com/spf description: prod2 security: [] tags: - name: Forms description: Determine all applicable forms and retrieve information for each - name: Questions description: Retrieve form and guide flow questions - name: PDF and Tax Parameters description: Retrieve pdf and tax parameter schemas and generate filled documents - name: Documentation description: Retrieve OpenApi configuration yaml and use it to generate a client api - name: Postman description: Resources for Postman - name: STE Mapping description: Retrieve SPF-to-STE tax parameter mappings paths: /guided-flows: post: tags: - Forms summary: Return applicable guided flows for given home and work addresses description: >- Returns applicable flows for the specified home and work address, used to filter the list of all applicable forms down to a list of required forms. operationId: getGuidedFlows requestBody: content: application/json: schema: $ref: '#/components/schemas/MultiStateDeterminationRequest' examples: 1 US home address and 1 US work address: summary: Simple description: 1 US home address and 1 US work address value: homeAddress: streetAddress1: 11 S Union St city: Montgomery state: AL zipCode: '36130' workAddresses: - streetAddress1: 64 N Union St city: Montgomery state: AL zipCode: '36130' includePreviewForms: false 1 US home address and 1 US work address, with nexus: summary: Nexus description: 1 US home address and 1 US work address, with nexus value: homeAddress: streetAddress1: 900 North Third Street city: Baton Rouge state: LA zipCode: '70802' workAddresses: - streetAddress1: 64 N Union St city: Montgomery state: AR zipCode: '36130' nexus: - AR - LA 1 Canadian home address and 1 Canadian work address: summary: Canada description: 1 Canadian home address and 1 Canadian work address value: homeAddress: streetAddress1: 5003 50 St streetAddress2: '' city: Red Deer provinceTerritory: AB postalCode: T4N 1Y2 workAddresses: - streetAddress1: 5003 50 St streetAddress2: '' city: Red Deer provinceTerritory: AB postalCode: T4N 1Y2 - streetAddress1: 2070 Harvey Ave streetAddress2: '#22' city: Kelowna provinceTerritory: BC postalCode: V1Y 8P8 required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Flows' examples: Flow determination resulting in a Flow set in which all flows require questions sets to determine forms to complete. The hasFlowQuestion will be set to true if a flow requires questions. This example response shows shows that the FEDERAL and AL_RESIDENT flow should be completed.: summary: US hasFlowQuestions is true description: >- Flow determination resulting in a Flow set in which all flows require questions sets to determine forms to complete. The hasFlowQuestion will be set to true if a flow requires questions. This example response shows shows that the FEDERAL and AL_RESIDENT flow should be completed. value: flows: - id: FEDERAL locality: FEDERAL hasFlowQuestions: true initialQuestionSetId: QS1 localityFullName: Federal - id: AL_RESIDENT locality: AL residencyStatus: RESIDENT hasFlowQuestions: true initialQuestionSetId: QS1 localityFullName: Alabama locationData: - id: home inputAddress: streetAddress1: 11 S Union St city: Montgomery state: AL zipCode: '36130' normalizedAddress: streetAddress1: 11 S Union St city: Montgomery state: AL zipCode: 36130-2102 addressResultMessages: - The corrected address is valid. [AS01] - >- The record was coded to the street level (Zip+4 for US, full postal code for CA). [GS01] addressErrorMessages: [] latitude: '32.376634' longitude: '-86.299645' geocoded: false verified: true - id: work1 inputAddress: streetAddress1: 64 N Union St city: Montgomery state: AL zipCode: '36130' normalizedAddress: streetAddress1: 64 N Union St city: Montgomery state: AL zipCode: 36130-3020 addressResultMessages: - The corrected address is valid. [AS01] - >- The record was coded to the street level (Zip+4 for US, full postal code for CA). [GS01] addressErrorMessages: [] latitude: '32.378229' longitude: '-86.299726' geocoded: false verified: true Flow determination resulting in a Flow set in which some, or all, flows do not require questions sets. In these instances, the formsToComplete field will contain a list of form ids that should be completed and the field hasFlowQuestions will be set to false. The example response shows that both the Federal and Kentucky flows will require question sets, but Illinois will not.: summary: US hasFlowQuestions is false description: >- Flow determination resulting in a Flow set in which some, or all, flows do not require questions sets. In these instances, the formsToComplete field will contain a list of form ids that should be completed and the field hasFlowQuestions will be set to false. The example response shows that both the Federal and Kentucky flows will require question sets, but Illinois will not. value: flows: - id: FEDERAL locality: FEDERAL hasFlowQuestions: true initialQuestionSetId: QS1 localityFullName: Federal - id: KY_RESIDENT locality: KY residencyStatus: RESIDENT hasFlowQuestions: true initialQuestionSetId: QS1 localityFullName: Kentucky - id: IL_NONRESIDENT locality: IL residencyStatus: NONRESIDENT hasFlowQuestions: false formsToComplete: - id: IL102 name: IL-W-5-NR title: Employee's Statement of Nonresidence in Illinois formVersion: 2011.1.0 formLocality: IL initialQuestionSet: QS1 localityFullName: Illinois locationData: - id: home inputAddress: streetAddress1: 239 West Main Street city: Richmond state: KY zipCode: '40475' normalizedAddress: streetAddress1: 239 W Main St city: Richmond state: KY zipCode: 40475-1592 addressResultMessages: - >- The address was verified but the unit number is missing or invalid. [AS02] - >- The record was geocoded down to the rooftop level, meaning the point is within the property boundaries, usually the center. [GS05] addressErrorMessages: [] latitude: '37.748458' longitude: '-84.295788' geocoded: true verified: true - id: work1 inputAddress: streetAddress1: 121 North La Salle Street city: Chicago state: IL zipCode: '60602' normalizedAddress: streetAddress1: 121 N La Salle St city: Chicago state: IL zipCode: 60602-1202 addressResultMessages: - >- The address was verified but the unit number is missing or invalid. [AS02] - Address does not receive mail at this time. [AS17] - >- The record was geocoded down to the rooftop level, meaning the point is within the property boundaries, usually the center. [GS05] addressErrorMessages: [] latitude: '41.88385' longitude: '-87.631661' geocoded: true verified: true Flow determination resulting in a Flow set in which all flows require questions sets to determine forms to complete. The hasFlowQuestion will be set to true if a flow requires questions. This example response shows shows that the CANADA_FEDERAL and AB_CANADA_RESIDENT flow should be completed.: summary: Canada hasFlowQuestions is true description: >- Flow determination resulting in a Flow set in which all flows require questions sets to determine forms to complete. The hasFlowQuestion will be set to true if a flow requires questions. This example response shows shows that the CANADA_FEDERAL and AB_CANADA_RESIDENT flow should be completed. value: flows: - id: CANADA_FEDERAL locality: CANADA_FEDERAL hasFlowQuestions: true initialQuestionSetId: QS1 localityFullName: Canada Federal - id: AB_CANADA_RESIDENT locality: AB residencyStatus: CANADA_RESIDENT hasFlowQuestions: true initialQuestionSetId: QS1 localityFullName: Alberta locationData: [] '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: path: uri=/spf/guided-flows status: Bad Request statusCode: 400 timestamp: '2020-01-01 12:00:00' errors: - field: workAddresses message: size must be between 1 and 10 rejectedValue: '[]' errorCount: 1 '403': description: Forbidden content: '*/*': schema: $ref: '#/components/schemas/ApiError' '404': description: '' content: {} '500': description: Internal Server Error content: '*/*': schema: $ref: '#/components/schemas/ApiError' security: - jwtToken: [] components: schemas: MultiStateDeterminationRequest: required: - homeAddress - workAddresses type: object properties: homeAddress: $ref: '#/components/schemas/Address' workAddresses: maxItems: 10 minItems: 1 type: array items: $ref: '#/components/schemas/Address' nexus: uniqueItems: true type: array items: type: string description: States and territories lockInLetters: uniqueItems: true type: array items: type: string description: States and territories interstateEmployee: type: boolean useAddressSuggestion: type: boolean Flows: type: object properties: errors: type: array items: $ref: '#/components/schemas/ValidationError' warnings: type: array items: type: string flows: type: array items: $ref: '#/components/schemas/Flow' locationData: type: array items: $ref: '#/components/schemas/LocationData' ApiError: type: object properties: path: type: string status: type: string statusCode: type: integer format: int32 timestamp: type: string format: date-time errors: type: array items: $ref: '#/components/schemas/ValidationError' errorCount: type: integer format: int32 Address: required: - city - streetAddress1 type: object properties: streetAddress1: pattern: ^[A-Za-z0-9#\/,.&'"\(\)\- –-—‘-’“-”À-ÖØ-öø-ÿ]*$ type: string description: >- Civic number and street name of the address. Cannot be null or empty. streetAddress2: pattern: ^[A-Za-z0-9#\/,.&'"\(\)\- –-—‘-’“-”À-ÖØ-öø-ÿ]*$ type: string description: >- Apartment, floor, unit number, or other address designation that is part of the address. city: pattern: ^[A-Za-z.,&'"\- –-—‘-’“-”À-ÖØ-öø-ÿ]+$ type: string description: City of the address. Cannot be null or empty. state: pattern: >- ^(AL|AK|AZ|AR|AS|CA|CO|CT|DE|DC|FM|FL|GA|GU|HI|ID|IL|IN|IA|KS|KY|LA|ME|MH|MD|MA|MI|MN|MS|MO|MT|NE|NV|NH|NJ|NM|NY|NC|ND|MP|OH|OK|OR|PW|PA|PR|RI|SC|SD|TN|TX|UT|VT|VA|VI|WA|WV|WI|WY)$ type: string description: States and territories zipCode: pattern: ^[0-9]{5}$|^[0-9]{5}-[0-9]{4}$|^[0-9]{9}$ type: string description: >- Address zip code. Must be exactly 5 or exactly 9 digits. All non-numeric characters will be automatically removed before validation (for example, 85260-2662 will be validated as 852602662). For SPF US only. stateEIN: pattern: ^[0-9a-zA-Z /_-]+$ type: string description: >- State employer identification number. Required by some US forms. Should only be specified on employer addresses. provinceTerritory: pattern: ^(AB|BC|MB|NB|NL|NT|NS|NU|ON|PE|QC|SK|YT)$ type: string description: States and territories postalCode: pattern: ^(?!.*[DFIOQU])[A-VXY][0-9][A-Z] ?[0-9][A-Z][0-9]$ type: string description: Postal code. For Canadian SPF only. description: >- The address sub-element of the employer element contains all data pertaining to an employer's physical address. ValidationError: type: object properties: field: type: string message: type: string rejectedValue: type: string Flow: type: object properties: id: type: string locality: type: string description: States and territories residencyStatus: type: string enum: - CANADA_RESIDENT - RESIDENT - NONRESIDENT hasFlowQuestions: type: boolean formsToComplete: type: array items: $ref: '#/components/schemas/Form' initialQuestionSetId: type: string localityFullName: type: string LocationData: type: object properties: id: type: string description: Location's ID inputAddress: $ref: '#/components/schemas/Address' normalizedAddress: $ref: '#/components/schemas/Address' addressResultMessages: type: object additionalProperties: $ref: '#/components/schemas/AddressResultStatus' description: Map of address IDs to address normalization and geocoding results addressErrorMessages: type: object additionalProperties: $ref: '#/components/schemas/AddressResultStatus' description: >- Map of address IDs to errors from address normalization and geocoding latitude: type: string description: Location's latitude longitude: type: string description: Location's longitude homePsdCode: type: string description: >- Location's Political Subdivision code, used by PA forms (e.g. PA114/CLGS-32-6). Only returned when at least one address is in PA. nullable: true homePsdRate: type: string description: >- Location's Political Subdivision tax rate, used by PA forms (e.g. PA114/CLGS-32-6). Only returned when at least one address is in PA. nullable: true homePsdMunicipality: type: string description: >- Location's Political Subdivision municipality, used by PA forms (e.g. PA114/CLGS-32-6). Only returned when at least one address is in PA. nullable: true homePsdCounty: type: string description: >- Location's Political Subdivision county, used by PA forms (e.g. PA114/CLGS-32-6). Only returned when at least one address is in PA. nullable: true workPsdCode: type: string description: >- Location's Political Subdivision code, used by PA forms (e.g. PA114/CLGS-32-6). Only returned when at least one address is in PA. nullable: true workPsdRate: type: string description: >- Location's Political Subdivision tax rate, used by PA forms (e.g. PA114/CLGS-32-6). Only returned when at least one address is in PA. nullable: true workPsdMunicipality: type: string description: >- Location's Political Subdivision municipality, used by PA forms (e.g. PA114/CLGS-32-6). Only returned when at least one address is in PA. nullable: true workPsdCounty: type: string description: >- Location's Political Subdivision county, used by PA forms (e.g. PA114/CLGS-32-6). Only returned when at least one address is in PA. nullable: true homeSchoolDistrictName: type: string description: >- Location's associated school district name, used by OH forms, only returned if address is a resident address in OH nullable: true homeSchoolDistrictCode: type: string description: >- Location's associated school district code, used by OH forms, only returned if address is a resident address in OH nullable: true workSchoolDistrictName: type: string description: >- Location's associated school district name, used by OH forms, only returned if address is a work address in OH nullable: true workSchoolDistrictCode: type: string description: >- Location's associated school district code, used by OH forms, only returned if address is a work address in OH nullable: true homeCountyName: type: string description: >- Location's county name, used by MD and IN forms, only returned if address is a resident address in MD/IN nullable: true workCountyName: type: string description: >- Location's county name, used by MD and IN forms, only returned if address is a work address in MD/IN nullable: true verified: type: boolean geocoded: type: boolean Form: type: object properties: id: $ref: '#/components/schemas/WithholdingForm' name: type: string title: type: string formVersion: type: string formLocality: type: string description: States and territories formType: type: string enum: - CANADA_RESIDENT - RESIDENT - NON_RESIDENT - RESIDENT_OUT_OF_STATE - EXEMPT - MILITARY - EIC - LOCAL - PENSION - EXEMPT_STUDENT - EXEMPT_NATIVE_AMERICAN - NONRESIDENT_EMPLOYER - RESIDENT_ALLOWANCE_ADJ - NON_RESIDENT_FORT_CAMPBELL - EXEMPT_TAX_CREDIT - RESIDENT_PITTSBURGH - NON_RESIDENT_PITTSBURGH - TAX_ADJ - EXEMPT_MILITARY_SPOUSE recommended: type: boolean initialQuestionSet: type: string AddressResultStatus: type: object properties: message: type: string description: Short description describing the result code response description: type: string description: Long description describing the result code response description: Address geocoding and normalization result and/or error WithholdingForm: type: string description: >- Form IDs - Use the /getAllFormIds endpoint to get all withholding form IDs available securitySchemes: jwtToken: type: http scheme: bearer bearerFormat: JWT ````