API docs by Redocly

Franchise Systems Ai API (0.4.0)

Download OpenAPI specification:

Developer Support: bill@franchisesystems.ai

Authentication

All API endpoints require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API Key Types

Two kinds of API key can authenticate against this API. Both are used the same way — as a Bearer token, or in the apiKey body field of POST /new-lead.

Personal API keys

Attached to an individual user account and carry that account's permissions.

  1. Log into Franchise Systems Ai.
  2. Click your profile in the bottom left hand corner of the interface.
  3. Select "Settings".
  4. Generate a new API key at the bottom of the page.
  5. Store it securely - API keys are only shown once.
  • Only one key per account is valid at any given time; generating a new one revokes the previous key.

Organization API keys

Belong to the organization rather than to a single user, so integrations keep working as individual team members come and go.

  • Created and managed by an organization admin from the organization's settings.
  • Carry the organization's brand permissions.
  • An organization can hold multiple keys at once.
  • Each key can be given an optional expiry date and can be revoked individually, without affecting the organization's other keys.
  • Like personal keys, the value is only shown once at creation — store it securely.

Rate Limiting

  • A general purpose rate limit of 1000 requests per 15 minute period is applied to this API
  • If this does not meet your needs, please reach out for support

State Management Overview

The API manages franchise information across 69 jurisdictions:

United States (51)

  • Standard 2-letter state codes (e.g., ca = California, ny = New York)
  • dc = Washington, District of Columbia

US Territories (5)

  • Guam (usot_gu)
  • American Samoa (usot_as)
  • Northern Mariana Islands (usot_nmi)
  • Puerto Rico (usot_pr)
  • US Virgin Islands (usot_vi)

Canadian Provinces & Territories (13)

  • All 10 provinces: Newfoundland (ca_nl), Prince Edward Island (ca_pe), Nova Scotia (ca_ns), New Brunswick (ca_nb), Quebec (ca_qc), Ontario (ca_on), Manitoba (ca_mb), Saskatchewan (ca_sk), Alberta (ca_ab), British Columbia (ca_bc)
  • All 3 territories: Yukon (ca_yt), Northwest Territories (ca_nt), Nunavut (ca_nu)

Brands

List all accessible brands

Retrieve a list of all brands that the authenticated agent has access to. Ids returned should be referenced for usage in the "state" routes.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{}

Match external brand names

Map external brand names to FranchiseSystems brands. Call this when activating an integration or when the external brand name changes.

Each match pairs a FranchiseSystems brand ID with the brand name as it appears in your system. This stored name is returned in the GET /brands response as externalBrandName, allowing you to detect name divergence on demand.

Authorizations:
BearerAuth
Request Body schema: application/json
required
required
Array of objects [ 1 .. 100 ] items

Array of brand ID to external brand name mappings

Responses

Request samples

Content type
application/json
{
  • "matches": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Leads

Capture sales and marketing leads collected in external systems.

Create a lead

Capture a new sales or marketing lead for one of your matched brands. Use this to forward leads collected in your own systems (web forms, landing pages, partner integrations) into Franchise Systems Ai.

Authentication

Unlike the other endpoints in this API, /new-lead does not read the Authorization: Bearer header. Pass your API key in the apiKey field of the request body instead. The key must have the sales.write permission on the target brand.

Brand resolution

Identify the brand with the externalBrandId that Franchise Systems Ai issues to you. These identifiers are assigned and provided by Franchise Systems Ai directly — they are not values you choose, and they are unrelated to the POST /brands/match name mapping. If the identifier is not recognised, the request fails with 404 Brand not found.

Lead types

  • sales — creates a sales lead (applicant). If a lead already exists for the email on this brand, the request returns 409 and no lead is created.
  • marketing — creates a marketing prospect.
Request Body schema: application/json
required
apiKey
required
string

Your Franchise Systems API key. Sent in the request body rather than the Authorization header for this endpoint. Must have the sales.write permission on the target brand.

externalBrandId
required
string

Identifier for the target brand, assigned and provided to you by Franchise Systems Ai directly. Contact Franchise Systems Ai to obtain the identifier for each brand you integrate with — it is not a value you choose.

leadType
required
string
Enum: "sales" "marketing"
  • sales — creates a sales lead (applicant).
  • marketing — creates a marketing prospect.
firstName
required
string
lastName
string
email
required
string <email>
phone
string
utmParams
string

UTM tracking parameters encoded as a JSON string — a flat object of UTM keys to string values (e.g. utm_source, utm_medium, utm_campaign). FSAI parses this to derive the lead's source.

additionalFields
string

Custom field submissions encoded as a JSON string — an array of { "fieldId": string, "value": string | number | boolean | string[] } objects. Each fieldId corresponds to one of the brand's configured custom form fields, and the field IDs are provided to you by Franchise Systems Ai directly. Contact Franchise Systems Ai for the IDs of the fields you want to populate.

Responses

Request samples

Content type
application/json
Example
{
  • "apiKey": "YOUR_API_KEY",
  • "externalBrandId": "ext-brand-42",
  • "leadType": "sales",
  • "firstName": "Jane",
  • "lastName": "Doe",
  • "email": "jane.doe@example.com",
  • "phone": "+15551234567",
  • "utmParams": "{\"utm_source\":\"partner\",\"utm_medium\":\"referral\",\"utm_campaign\":\"spring\"}"
}

Response samples

Content type
application/json
Example
{
  • "message": "Sales lead added"
}

States

Operations related to brand and state specific franchising information

Get state franchising status for a brand

Retrieve the franchising status for all states for a specific brand

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the brand

Responses

Response samples

Content type
application/json
{
  • "ak": false,
  • "al": true,
  • "ar": false,
  • "az": true,
  • "ca": true,
  • "co": false,
  • "ct": false,
  • "dc": false,
  • "de": false,
  • "fl": false,
  • "ga": false,
  • "hi": false,
  • "ia": false,
  • "id": false,
  • "il": false,
  • "in": false,
  • "ks": false,
  • "ky": false,
  • "la": false,
  • "ma": false,
  • "md": false,
  • "me": false,
  • "mi": false,
  • "mn": false,
  • "mo": false,
  • "ms": false,
  • "mt": false,
  • "nc": false,
  • "nd": false,
  • "ne": false,
  • "nh": false,
  • "nj": false,
  • "nm": false,
  • "nv": false,
  • "ny": false,
  • "oh": false,
  • "ok": false,
  • "or": false,
  • "pa": false,
  • "ri": false,
  • "sc": false,
  • "sd": false,
  • "tn": false,
  • "tx": false,
  • "ut": false,
  • "va": false,
  • "vt": false,
  • "wa": false,
  • "wi": false,
  • "wv": false,
  • "wy": false,
  • "usot_gu": false,
  • "usot_as": false,
  • "usot_nmi": false,
  • "usot_pr": false,
  • "usot_vi": false,
  • "ca_nl": false,
  • "ca_pe": false,
  • "ca_ns": false,
  • "ca_nb": false,
  • "ca_qc": false,
  • "ca_on": false,
  • "ca_mb": false,
  • "ca_sk": false,
  • "ca_ab": false,
  • "ca_bc": false,
  • "ca_yt": false,
  • "ca_nt": false,
  • "ca_nu": false
}

Set actively franchising status

Update whether a brand is actively franchising in a specific state

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the brand

stateId
required
string (State)
Enum: "ak" "al" "ar" "az" "ca" "co" "ct" "dc" "de" "fl" "ga" "hi" "ia" "id" "il" "in" "ks" "ky" "la" "ma" "md" "me" "mi" "mn" "mo" "ms" "mt" "nc" "nd" "ne" "nh" "nj" "nm" "nv" "ny" "oh" "ok" "or" "pa" "ri" "sc" "sd" "tn" "tx" "ut" "va" "vt" "wa" "wi" "wv" "wy" "usot_gu" "usot_as" "usot_nmi" "usot_pr" "usot_vi" "ca_nl" "ca_pe" "ca_ns" "ca_nb" "ca_qc" "ca_on" "ca_mb" "ca_sk" "ca_ab" "ca_bc" "ca_yt" "ca_nt" "ca_nu"

State identifier (US state abbreviation or Canadian province code)

Request Body schema: application/json
required
is_active
required
boolean

Whether the brand is actively franchising in this state

Responses

Request samples

Content type
application/json
{
  • "is_active": true
}

Response samples

Content type
application/json
{ }

Get state overview for a brand

Retrieve detailed state-specific information for a brand

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the brand

stateId
required
string (State)
Enum: "ak" "al" "ar" "az" "ca" "co" "ct" "dc" "de" "fl" "ga" "hi" "ia" "id" "il" "in" "ks" "ky" "la" "ma" "md" "me" "mi" "mn" "mo" "ms" "mt" "nc" "nd" "ne" "nh" "nj" "nm" "nv" "ny" "oh" "ok" "or" "pa" "ri" "sc" "sd" "tn" "tx" "ut" "va" "vt" "wa" "wi" "wv" "wy" "usot_gu" "usot_as" "usot_nmi" "usot_pr" "usot_vi" "ca_nl" "ca_pe" "ca_ns" "ca_nb" "ca_qc" "ca_on" "ca_mb" "ca_sk" "ca_ab" "ca_bc" "ca_yt" "ca_nt" "ca_nu"

State identifier (US state abbreviation or Canadian province code)

Responses

Response samples

Content type
application/json
{
  • "state": {
    }
}

Update state overview for a brand

Update state-specific franchising information for a brand

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the brand

stateId
required
string (State)
Enum: "ak" "al" "ar" "az" "ca" "co" "ct" "dc" "de" "fl" "ga" "hi" "ia" "id" "il" "in" "ks" "ky" "la" "ma" "md" "me" "mi" "mn" "mo" "ms" "mt" "nc" "nd" "ne" "nh" "nj" "nm" "nv" "ny" "oh" "ok" "or" "pa" "ri" "sc" "sd" "tn" "tx" "ut" "va" "vt" "wa" "wi" "wv" "wy" "usot_gu" "usot_as" "usot_nmi" "usot_pr" "usot_vi" "ca_nl" "ca_pe" "ca_ns" "ca_nb" "ca_qc" "ca_on" "ca_mb" "ca_sk" "ca_ab" "ca_bc" "ca_yt" "ca_nt" "ca_nu"

State identifier (US state abbreviation or Canadian province code)

Request Body schema: application/json
required
max_locations
number or null

Maximum number of locations allowed in this state

registration_expires_at
string or null <date-time>

When the current registration expires

fdd_filed_at
string or null <date-time>

When the FDD was filed

fdd_filing_required
boolean or null

Whether FDD filing is required in this state

fdd_renewal_deadline
string or null <date-time>

Deadline for FDD renewal

franchise_fee_collection_rules
string or null

Rules governing franchise fee collection

governing_agency_address
string or null

Address of the governing agency

governing_agency_email
string or null <email>

Email of the governing agency

governing_agency_name
string or null

Name of the governing agency

governing_agency_phone
string or null

Phone number of the governing agency

insurance_requirements
string or null

Insurance requirements for franchisees

other_notes
string or null

Additional notes or comments

registration_date
string or null <date-time>

Date of registration

registration_or_filing_fee
number or null

Cost of registration or filing fee

registration_required
boolean or null

Whether registration is required in this state

registration_status
string (StateRegistrationStatus)
Enum: "none" "filed_not_registered" "filed_registered"

Current registration status for the brand in this state. This field drives several pieces of UI in the FSAI dashboard with absolute authority — set it to reflect the real-world status, and the dashboard will respond accordingly.

  • filed_registered — brand is registered and active in this state. FSAI renders: green state icon in the detail panel, green map fill, and (when registration_expires_at is set) a "Registered" / "Expiring Soon" / "Expired" list tag depending on the expiry date.
  • none — brand is not registered in this state. FSAI renders: red state icon, red map fill when registration_required is true, and a "Registration Required" list tag (only when registration_required is true).
  • filed_not_registered — deprecated, do not use. FSAI treats this value as none (red) for safety. Send none or filed_registered instead.

Related display fields the dashboard derives from this value plus registration_required and registration_expires_at: list-view tag, state-icon colour, and map fill colour.

renewal_fee
number or null

Cost of renewal fee

renewal_fee_timeframe
string (AgreementFeeTimeframe)
Enum: "annually" "biannually" "monthly" "quarterly" "yearly"

Timeframe for fee payments

special_state_addenda_requirements
string or null

Special state-specific addenda requirements

surety_bond_requirements
string or null

Surety bond requirements

trademark_requirements
string or null

Trademark-related requirements

annual_renewal_information
string or null

Information about annual renewal process

initial_registration_information
string or null

Information about initial registration process

waiting_period_information
string or null

Information about waiting periods

fdd_comment_letters
number or null

Number of comment letters received for FDD

fdd_filing_duration_days
number or null

Duration in days for FDD filing process

fdd_filing_type
string or null
Enum: "initial" "renewal" "amendment" "exemption"

Type of the current/most-recent FDD filing in this state. Drives the "X Filing" copy shown in the FSAI dashboard's Filing section (e.g. renewal → "Renewal Filing"). Choose the value that matches the filing this state is currently reporting.

is_filing_open
boolean

Whether a filing is currently open / in progress with the regulator for this state. When true, FSAI surfaces a blue indicator on the state icon to signal an in-progress filing.

financial_assurance
string or null

Financial assurance requirements

general_information
string or null

General information and notes

is_action_required
boolean or null

Whether action is required for this state

legal_representative_email
string or null <email>

Email of the legal representative

legal_representative_first_name
string or null

First name of the legal representative

legal_representative_last_name
string or null

Last name of the legal representative

legal_representative_phone
string or null

Phone number of the legal representative

legal_representative_role
string or null

Role/title of the legal representative

Responses

Request samples

Content type
application/json
{
  • "max_locations": 0,
  • "registration_expires_at": "2019-08-24T14:15:22Z",
  • "fdd_filed_at": "2019-08-24T14:15:22Z",
  • "fdd_filing_required": true,
  • "fdd_renewal_deadline": "2019-08-24T14:15:22Z",
  • "franchise_fee_collection_rules": "string",
  • "governing_agency_address": "string",
  • "governing_agency_email": "user@example.com",
  • "governing_agency_name": "string",
  • "governing_agency_phone": "string",
  • "insurance_requirements": "string",
  • "other_notes": "string",
  • "registration_date": "2019-08-24T14:15:22Z",
  • "registration_or_filing_fee": 0,
  • "registration_required": true,
  • "registration_status": "filed_registered",
  • "renewal_fee": 0,
  • "renewal_fee_timeframe": "yearly",
  • "special_state_addenda_requirements": "string",
  • "surety_bond_requirements": "string",
  • "trademark_requirements": "string",
  • "annual_renewal_information": "string",
  • "initial_registration_information": "string",
  • "waiting_period_information": "string",
  • "fdd_comment_letters": 0,
  • "fdd_filing_duration_days": 0,
  • "fdd_filing_type": "initial",
  • "is_filing_open": true,
  • "financial_assurance": "string",
  • "general_information": "string",
  • "is_action_required": true,
  • "legal_representative_email": "user@example.com",
  • "legal_representative_first_name": "string",
  • "legal_representative_last_name": "string",
  • "legal_representative_phone": "string",
  • "legal_representative_role": "string"
}

Response samples

Content type
application/json
{ }

Update state filing activity for a brand

Update the filing activity records for a specific brand-state combination

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the brand

stateId
required
string (State)
Enum: "ak" "al" "ar" "az" "ca" "co" "ct" "dc" "de" "fl" "ga" "hi" "ia" "id" "il" "in" "ks" "ky" "la" "ma" "md" "me" "mi" "mn" "mo" "ms" "mt" "nc" "nd" "ne" "nh" "nj" "nm" "nv" "ny" "oh" "ok" "or" "pa" "ri" "sc" "sd" "tn" "tx" "ut" "va" "vt" "wa" "wi" "wv" "wy" "usot_gu" "usot_as" "usot_nmi" "usot_pr" "usot_vi" "ca_nl" "ca_pe" "ca_ns" "ca_nb" "ca_qc" "ca_on" "ca_mb" "ca_sk" "ca_ab" "ca_bc" "ca_yt" "ca_nt" "ca_nu"

State identifier (US state abbreviation or Canadian province code)

Request Body schema: application/json
required
required
Array of objects (FilingActivity)

Array of filing activities to update for the brand-state combination. Note: This operation completely replaces all existing filing activities with the provided array. The entire activity array must always be passed, as the previous activity records will be wiped and reset with what is provided here.

Responses

Request samples

Content type
application/json
{
  • "activity": [
    ]
}

Response samples

Content type
application/json
{ }

Bulk update filing activities for multiple states

Update filing activity records for multiple states of a single brand in one transactional operation.

Modes:

  • replace (default): Replaces all existing activities for each state with the provided activities
  • append: Adds new activities to existing ones without deleting

Mode Resolution:

  • Request-level mode applies to all states unless overridden
  • Per-state mode overrides the request-level mode for that specific state

Transaction Behavior: All updates are applied within a single database transaction. If any update fails, the entire operation is rolled back and no changes are persisted.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the brand

Request Body schema: application/json
required
mode
string (FilingActivityMode)
Enum: "replace" "append"

Mode for updating filing activities:

  • replace: Delete all existing activities and insert new ones
  • append: Add new activities without removing existing ones
required
Array of objects (StateFilingActivityUpdateItem) [ 1 .. 69 ] items

Array of state filing activity updates (maximum 69 jurisdictions)

Responses

Request samples

Content type
application/json
{
  • "mode": "replace",
  • "states": [
    ]
}

Response samples

Content type
application/json
{
  • "updated": 2,
  • "state_ids": [
    ]
}

Get all filing activities for a brand

Retrieve all filing activities across all states for a specific brand.

Returns a list of states with their associated filing activities. Only states that have filing activity records are included in the response.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the brand

Responses

Response samples

Content type
application/json
{
  • "activities": [
    ]
}

Get all states overview for a brand

Retrieve state overview information for all or specified states for a brand.

Use the optional state_ids query parameter to filter results to specific states. If state_ids is not provided, returns all states that have records for the brand.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the brand

query Parameters
state_ids
string
Example: state_ids=ca,ny,tx

Comma-separated list of state codes to filter results (e.g., "ca,ny,tx")

Responses

Response samples

Content type
application/json
{
  • "states": [
    ]
}

Bulk update states for a brand

Update multiple states for a single brand in one transactional operation.

Transaction Behavior: All updates are applied within a single database transaction. If any update fails, the entire operation is rolled back and no changes are persisted.

Validation: All state updates are validated before the transaction begins. If validation fails for any state, detailed error messages are returned with indices for easy identification.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the brand

Request Body schema: application/json
required
required
Array of objects (StateUpdateItem) [ 1 .. 69 ] items

Array of state updates (maximum 69 jurisdictions - all US states, DC, territories, and Canadian provinces)

Responses

Request samples

Content type
application/json
{
  • "states": [
    ]
}

Response samples

Content type
application/json
{
  • "updated": 2,
  • "state_ids": [
    ]
}

Bulk update states across multiple brands

Update states for multiple brands in one transactional operation.

Transaction Behavior: All updates across all brands are applied within a single database transaction. If any update fails for any brand, the entire operation is rolled back and no changes are persisted.

Validation: All state updates for all brands are validated before the transaction begins. If validation fails for any state in any brand, detailed error messages are returned with brand IDs and indices for easy identification.

Authorization: The authenticated user must have write access to all brands in the request.

Authorizations:
BearerAuth
Request Body schema: application/json
required
required
Array of objects (BrandStateUpdateItem) [ 1 .. 50 ] items

Array of brand updates (maximum 50 brands)

Responses

Request samples

Content type
application/json
{
  • "brands": [
    ]
}

Response samples

Content type
application/json
{
  • "updated": 4,
  • "results": [
    ]
}

Get all signing links for a brand

Retrieve the default signing link and all state-specific signing links for a brand.

Use this endpoint to verify which signing links are currently configured. The default field contains the fallback signing link set on the external management organization. The states array contains all state-specific overrides.

Authorizations:
BearerAuth
path Parameters
brandId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

UUID of the brand

Responses

Response samples

Content type
application/json
{}

Signing Events

Receive signing events from external systems. Events track document signing status and trigger application workflow side effects.

Report a signing event

Receive a normalized document signing event from an external system.

When a DocuSign PowerForm event occurs (delivered, completed, voided, or declined), the external system forwards the event to this endpoint. The fsai_reference_id in the payload is used to look up the corresponding signing reference and update its status.

On completion, the applicant's FDD step is automatically marked as complete and the FDD lockout period begins.

Authorizations:
BearerAuth
Request Body schema: application/json
required
event_type
required
string
Enum: "envelope-completed" "envelope-voided" "envelope-declined" "envelope-delivered"

The type of signing event.

Deprecated: envelope-voided is deprecated and will be removed in a future version. It is still accepted for backward compatibility, but new integrations should not rely on it.

fsai_reference_id
required
string <uuid>

The FSAI reference ID that was embedded in the PowerForm URL via the EnvelopeField_fsai-reference-id parameter. This ID is created when the signing URL is constructed and links back to the applicant's signing request.

envelope_id
string

Optional DocuSign envelope ID. Not used for processing — the signing request is identified via fsai_reference_id. Included for audit trail purposes and stored alongside the event data.

status
required
string
Enum: "completed" "voided" "declined" "viewed" "started"

The current status of the envelope

completed_at
string <date-time>

When the envelope was completed (required when status is completed)

object

Optional raw DocuSign Connect event data for audit purposes

Responses

Request samples

Content type
application/json
{
  • "event_type": "envelope-completed",
  • "fsai_reference_id": "1c9ca540-47e5-4513-9c77-8d80bade9773",
  • "envelope_id": "string",
  • "status": "completed",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "raw_event": { }
}

Response samples

Content type
application/json
{
  • "success": true
}