Connect your software to Fictix

Point your server's provider client at a generated company's Fictix URL, add its runtime API key, and send a supported provider request. Records and writes belong to that synthetic company. Fictix does not log in to your vendor account, send real messages, run ads, or move money through a bank.

1. Choose the environment and company

Public catalog snapshots observed on October 28, 2026 report 60 entries in both staging and production: 59 marked available/selectable and one FCI execute preview that is not selectable. All 60 report approximate fidelity. These are catalog reports, not proof that provider requests work or strict upstream API parity. The published first-request templates were tested in staging only. Use the first-request directory to check catalog status for each provider; workflow coverage lists the supported staging operations and limits.

To evaluate the expanded integrations, sign in at staging.fictix.ai, create or select a company, and choose the integrations your software needs. Onboarding, the connector picker, and the add-integration menu use the deployed catalog. Your organization's plan and the company's selected services still determine access.

Open the company's API page to select a provider and copy its API URL, key, and first request. The Connect to your builder panel also provides setup details. Keep the key and API origin in the same environment.

2. Choose a runtime key

Use a Company API key for one company. For one key across your current and future companies, staging organization admins can use an organization API key. Both authenticate with X-API-Key; neither is a vendor OAuth token.

Choose the scopes needed by your app when issuing the key. The Console's Full runtime organization-key setting includes read, write, and execute. It does not include the separate ground_truth scope. Keys never override plan entitlements or grant management access.

Keep credentials in your server's secret store. A browser app calls your own server, which attaches the key when calling Fictix. Use the existing browser-builder proxy guidance for browser apps.

3. Set the base URL

Copy the slug and key from the selected staging company:

export FICTIX_API_ORIGIN="https://api-staging.fictix.ai"
export FICTIX_PROJECT_SLUG="replace_with_company_slug"
export FICTIX_PROJECT_API_KEY="replace_with_company_key"

These examples use a company key. For an organization key, send $FICTIX_ORGANIZATION_API_KEY in the same header and select a company by its slug. The organization-key guide shows how to list your company IDs and slugs.

For example, Stripe's provider base is https://api-staging.fictix.ai/api/v1/orgs/{slug}/native/stripe. Append v1/customers for its first read:

curl --fail-with-body -sS \
  "$FICTIX_API_ORIGIN/api/v1/orgs/$FICTIX_PROJECT_SLUG/native/stripe/v1/customers" \
  -H "X-API-Key: $FICTIX_PROJECT_API_KEY"

If an SDK adds its own /v1, /api, or service prefix, configure its server URL so the resulting request matches the full path in the first-request directory. Configure its transport to send the Fictix header. An SDK that cannot change its host or headers needs a custom transport or a direct HTTP client. Vendor login flows and SDK defaults are not Fictix authentication.

4. Check discovery and the response

The catalog is public. Query the environment your server actually uses:

curl --fail-with-body -sS \
  "$FICTIX_API_ORIGIN/api/v1/catalog/connector-capabilities"

Find your provider by id. Check status, ui_selectable, native_supported, contract_surfaces, and limitations. FCI has an execute surface and no native surface. A missing provider is unavailable in that environment. Relay Financial has no implemented direct API contract and is not in the available catalog.

Provider responses retain their own envelopes, pagination, and content types:

• REST requests usually use JSON, but their list fields differ by provider.
• Linear and Monday use GraphQL over POST. Inspect the GraphQL errors field.
• Sage Intacct uses XML. Inspect every returned operation status.
• Expensify uses a URL-encoded requestJobDescription form field. Check responseCode as well as the HTTP status.
• Execute responses can use HTTP 200 with status: "error". Require status: "success" before consuming outputs.

Use the request bodies and media types in the first-request directory. A POST read does not become a write merely because of its HTTP method.

5. Use FCI through execute

Read the company's id from GET /api/v1/orgs/{slug}/info, the API page's generated request, or the organization company directory. Put that company project ID in the legacy org_id body field. The workspace organization ID and the URL's company slug are different identifiers.

curl --fail-with-body -sS -X POST \
  "$FICTIX_API_ORIGIN/api/v1/orgs/$FICTIX_PROJECT_SLUG/execute" \
  -H "X-API-Key: $FICTIX_PROJECT_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{"org_id":"replace_with_company_project_id","user_id":"your-integration","turn_id":"replace_with_unique_request_id","capability_key":"fci.cash","args":{}}'

This key needs both read and execute. FCI returns derived financial summaries and retains preview status. Confirm its capability is available for your company; it is not selectable in the standard connector picker. There is no /native/fci first request.

6. Make writes reproducible

Native writes should include a fresh Idempotency-Key per operation. Reuse it only for a retry with the same request and payload. Execute requests use a unique turn_id per operation; preserve it on retries. Follow the provider's documented exception where its own idempotency field is supported.

Read the resulting object back to verify persistence. Use each provider's pagination contract; canonical limit/offset is not a universal native API pagination scheme. Unsupported operations return errors rather than extending the vendor contract automatically.

If a call returns 401, check the environment, expiry, and revocation state of the key. A 402 with feature_not_entitled means the organization lacks the required plan feature; native integration APIs require native.genome, available on Developer or higher. Creating a new key does not change plan access. Canonical REST data can still be available on your existing plan. For 403, check the key's company or organization and required scopes. For 400, 404, or 422, compare the exact method, path, body, and content type with the documented workflow.

The Company API reference describes runtime routing and schemas. The provider guides supply the concrete vendor paths hidden behind its generic native route. Use the Partner API only for an approved external management integration.