US Business Verification

Overview

FrankieOne verifies US-registered businesses against authoritative US sources, returning Secretary of State filing records, the business’s registered jurisdiction, and its officers. US verification is triggered automatically by the address country — you do not need to select a different workflow or endpoint. When you create an organization with a US address, the platform routes the verification to the appropriate US data source, and the enriched data is written back onto the same organization entity. The flow is the same four steps used for any KYB verification:

1. Create the organization

Submit the business’s name, address and EIN to create the entity.

2. Execute a workflow

Run GLB-Organization-Profile against the returned entityId.

3. Poll for the result

Workflows run asynchronously — poll until the execution completes.

4. Get the enriched organization

Retrieve the organization to see the verified registration data.

Implementation Guide

Prerequisites

Before you begin, ensure you have:

An account configured with a US-enabled KYB workflow.
API credentials — your api_key and X-Frankie-CustomerId.
Your X-Frankie-CustomerChildID, if your account is structured with child customer accounts. This header is optional; include it on every request when you need to act on behalf of a specific child account, and omit it otherwise.
Confirmation from your Customer Success Manager that US jurisdiction support is enabled on your account.

The examples in this guide show the api_key and X-Frankie-CustomerId headers only. If you use child customer accounts, add X-Frankie-CustomerChildID to each request as well.

Step 1: Create a US organization

To create a US-based organization, submit at least one address with country: "USA" in your POST /v2/organizations request. US verification is triggered automatically based on the address country.

Request Body Fields

Field	Required	Description	Example
`organization.addresses[]`	Yes	At least one business address, with `country` set to `USA`.	`{"country":"USA","longForm":"1100 Maple Dr, Phoenix, AZ 85001"}`
`organization.details.name.name`	Yes	Legal registered business name.	`"Acme Corp"`
`organization.jurisdictionalInformation.taxpayerIdentificationNumber.value`	Yes	The business’s EIN.	`"55-5666777"`
`serviceName`	Yes	Selects the service profile to assess against.	`"DEFAULT"`

Request

curl --location 'https://api.uat.frankie.one/v2/organizations' \
--header 'api_key: YOUR_API_KEY' \
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
--header 'Content-Type: application/json' \
--data '{
    "organization": {
        "addresses": [
            { "country": "USA", "longForm": "1100 Maple Dr, Phoenix, AZ 85001" }
        ],
        "details": {
            "name": { "name": "Acme Corp" }
        },
        "jurisdictionalInformation": {
            "taxpayerIdentificationNumber": { "value": "55-5666777" }
        }
    },
    "serviceName": "DEFAULT"
}'

Response

A successful request returns 201 Created.

{
    "organization": {
        "addresses": [
            {
                "addressId": "019f3ba1-6b80-7b40-996d-a9ae88292a1b",
                "country": "USA",
                "longForm": "1100 Maple Dr, Phoenix, AZ 85001",
                "sourceId": "725e6311-4b23-4be2-924a-c350bd004d03",
                "status": "CURRENT",
                "type": "BUSINESS"
            }
        ],
        "createdAt": "2026-07-07T08:11:02Z",
        "details": {
            "name": { "name": "Acme Corp", "sourceId": "725e6311-4b23-4be2-924a-c350bd004d03", "type": "PRIMARY" }
        },
        "entityId": "019f3ba1-6b80-7b29-8d39-b9f1fdc28db7",
        "entityType": "ORGANIZATION",
        "informationSources": {
            "725e6311-4b23-4be2-924a-c350bd004d03": {
                "provider": "MANUAL",
                "source": "Unknown",
                "isAuthoritative": false
            }
        },
        "jurisdictionalInformation": {
            "taxpayerIdentificationNumber": { "value": "55-5666777", "sourceId": "725e6311-4b23-4be2-924a-c350bd004d03" }
        },
        "schemaVersion": 2
    },
    "requestId": "01KWXT2THHWJ2EWPY7G6KQKRMY",
    "serviceProfiles": [
        {
            "entityId": "019f3ba1-6b80-7b29-8d39-b9f1fdc28db7",
            "serviceName": "DEFAULT",
            "serviceProfileId": "5cfdade0-71c7-4c7a-b348-2a53959a9caa",
            "state": "INIT"
        }
    ]
}

At this point, informationSources reflects only what you submitted — provider is MANUAL and isAuthoritative is false. Each entry is keyed by a generated sourceId, one per data source contributing to the record. Verified registration data is added once you run the workflow in Step 2.

Retain the entityId from the response — you need it for every subsequent call.

Step 2: Execute the workflow

Run the GLB-Organization-Profile workflow against the organization’s entityId.

Request

curl --location 'https://api.uat.frankie.one/v2/organizations/workflows/GLB-Organization-Profile/execute' \
--header 'api_key: YOUR_API_KEY' \
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
--header 'Content-Type: application/json' \
--data '{
    "entityId": "019f3ba1-6b80-7b29-8d39-b9f1fdc28db7",
    "serviceName": "DEFAULT"
}'

Response

{
    "entityId": "019f3ba1-6b80-7b29-8d39-b9f1fdc28db7",
    "requestId": "01KWXT2VG40KSG1X0RKBJHPKZF",
    "serviceName": "DEFAULT",
    "serviceProfileId": "5cfdade0-71c7-4c7a-b348-2a53959a9caa",
    "workflowExecutionId": "01KWXT2WH7TZEZ6987AE9VB1TN"
}

Retain the workflowExecutionId — you need it to poll for the result.

Step 3: Poll for results

Workflow executions run asynchronously. Poll for the execution status using the workflowExecutionId returned in Step 2.

Request

curl --location 'https://api.uat.frankie.one/v2/organizations/{entityId}/serviceprofiles/DEFAULT/workflows/GLB-Organization-Profile/executions/{workflowExecutionId}' \
--header 'api_key: YOUR_API_KEY' \
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID'

Response

{
    "workflowResult": {
        "workflowExecutionId": "01KWXT2WH7TZEZ6987AE9VB1TN",
        "workflowExecutionState": "COMPLETED",
        "status": "COMPLETE"
    }
}

workflowResult.workflowExecutionState tells you whether the execution has finished:

State	Meaning
`IN_PROGRESS`	Still running — keep polling every few seconds.
`COMPLETED`	Finished. Retrieve the enriched organization and verification results.
`CANCELED`	Canceled before completion.
`TERMINATED`	Terminated before completion.
`ERROR`	Encountered an error.
`TIMEOUT`	Timed out.

Check both fields. workflowExecutionState reports whether the execution finished; workflowResult.status carries the verification outcome (COMPLETE, REVIEW, PASS, FAIL, and others). A COMPLETED execution can still return an outcome such as REVIEW that requires a closer look.

Step 4: Get the enriched organization

Once the workflow completes, retrieve the organization to see the verified data that has been added to it.

Request

curl --location 'https://api.uat.frankie.one/v2/organizations/{entityId}' \
--header 'api_key: YOUR_API_KEY' \
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID'

Response

{
    "organization": {
        "addresses": [
            { "addressId": "019f3ba1-6b80-7b40-996d-a9ae88292a1b", "country": "USA", "longForm": "1100 Maple Dr, Phoenix, AZ 85001", "status": "CURRENT", "type": "BUSINESS" },
            { "addressId": "019f3ba1-7c0a-76ec-bafc-25dcf3e12294", "country": "USA", "longForm": "1000 Elm St, Atlanta, GA 30301", "subdivision": "GA", "type": "OTHER" }
        ],
        "details": {
            "jurisdiction": { "country": "USA", "subdivision": "GA" },
            "name": { "name": "Acme Corp", "type": "PRIMARY" },
            "registrationDetails": [
                {
                    "registeredName": { "name": "Acme Corp" },
                    "registeredSubdivision": "GA",
                    "registrationNumber": "FN-XXXXXXX",
                    "registrationStatus": { "unstructured": { "code": "GOOD_STANDING", "description": "Active-Good Standing" } },
                    "registry": "SOS",
                    "registryDescription": "https://ecorp.sos.ga.gov/BusinessSearch"
                }
            ],
            "status": { "unstructured": { "code": "GOOD_STANDING", "description": "Active-Good Standing" } }
        },
        "entityId": "019f3ba1-6b80-7b29-8d39-b9f1fdc28db7",
        "informationSources": {
            "d76b9d14-3661-484d-83d0-cc45ca86688e": { "provider": "<provider>", "isAuthoritative": true, "providerReference": "d1ce51c7-8f1b-4182-ae6d-bc14c7c1f167" }
        },
        "officials": [
            { "entityId": "c8a78d65-a4b4-4471-90c3-12370b0e11cc", "entityType": "INDIVIDUAL", "role": { "code": "CE", "description": "CEO" }, "title": "CEO" }
        ]
    }
}

What Verification Adds

Field	What It Contains
`details.jurisdiction`	The state in which the business is registered, as `country` and `subdivision`.
`details.registrationDetails[]`	The Secretary of State filing record — registered name, subdivision, registration number, status, and a link to the state registry. `registry` is `SOS`.
`details.status`	The business’s overall standing, for example `GOOD_STANDING`.
`officials[]`	The business’s officers, each with an `entityId`, `role` code and `title`.
`informationSources`	Gains an entry with `isAuthoritative: true` and a `providerReference`, alongside the original `MANUAL` entry. The `provider` value identifies the verifying data source — shown as `<provider>` in the example above.
`addresses[]`	May gain additional addresses discovered during verification, distinguished by `type`.

Officers returned in officials[] are created as INDIVIDUAL entities. You can run individual KYC checks against them using their entityId.

Next Steps

Once verification has completed, parse the workflowResult object to understand the outcome of every check. For a complete breakdown of every field in the response, see Interpreting Workflow Results.

​Overview

​Implementation Guide

​Prerequisites

​Step 1: Create a US organization

​Request Body Fields

​Request

​Response

​Step 2: Execute the workflow

​Request

​Response

​Step 3: Poll for results

​Request

​Response

​Step 4: Get the enriched organization

​Request

​Response

​What Verification Adds

​Next Steps

​Additional Resources

Overview

Implementation Guide

Prerequisites

Step 1: Create a US organization

Request Body Fields

Request

Response

Step 2: Execute the workflow

Request

Response

Step 3: Poll for results

Request

Response

Step 4: Get the enriched organization

Request

Response

What Verification Adds

Next Steps

Additional Resources