# Quickstart

Use the Flownally API to keep customer data and communication flows connected to the systems your team already runs.

Flownally brings WhatsApp, Messenger, and Instagram into one clear inbox. The API is for the server-side work around that inbox: syncing contacts, updating operational data, reading conversation records, and supporting automation that should run without someone clicking through the app.

## What you need

- A Flownally tenant with API access.
- A service-account API key or another bearer token for server-side access.
- A terminal with curl, or an HTTP client that can send JSON.
- A clear integration owner who can rotate credentials and investigate failures.

## Choose a first integration

Start with one small workflow. Prove that your credentials, tenant, and data shape are right before you connect more of the customer journey.

Good first integrations:

- import or update contacts from your CRM,
- add tags that help the inbox team triage conversations,
- read conversation or message data for reporting,
- subscribe to Webhooks so your system reacts to contact, conversation, or message changes,
- create service-account credentials for a backend worker.

Avoid starting with a broad, write-heavy sync. Flownally works best when automation stays understandable and operators can see what changed.

## Configure your shell

```bash
export FLOWNALLY_API_BASE_URL="https://api.flownally.com/v1"
export FLOWNALLY_API_TOKEN="replace-with-your-api-key"
```

## 1. Check your credentials

Start with `GET /contacts`. A successful response confirms that the token works for the tenant. The contacts reference documents query parameters and the response shape at [Get contacts](/reference/contacts#get-contacts).

```bash
curl -G "$FLOWNALLY_API_BASE_URL/contacts" \
  -H "Authorization: Bearer $FLOWNALLY_API_TOKEN" \
  -H "Accept: application/json"
```

## 2. Create or update customer data

Send `POST /contacts` with a JSON body. Phone numbers use E.164 format, and custom fields use the `customFields` object documented in the contact schema.

```bash
curl -X POST "$FLOWNALLY_API_BASE_URL/contacts" \
  -H "Authorization: Bearer $FLOWNALLY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace",
    "phone": "+15551234567",
    "customFields": {
      "source": "quickstart",
      "lifecycleStage": "lead"
    }
  }'
```

The full request and response schema is documented at [Create contact](/reference/contacts#create-contact). Use the same pattern for other resource groups: read the operation, send JSON with bearer auth, and handle the documented response shape.

## 3. Connect the API to the product flow

After the first request succeeds, decide where the API should support the app experience:

- Use contacts and tags to keep the shared inbox organized.
- Use journeys and chatbots to support repeatable customer communication.
- Use users and teams to align API work with operators in the app.
- Use service accounts and API keys for integrations that run on a schedule.

Keep human conversations in the app and backend automation in the API. That separation makes changes easier to audit and keeps customer communication clear.

## 4. Use the reference

Resource pages group related endpoints on one page. Use hash links to move between operations, then open the LLM menu next to a page title when you need the Markdown version for an assistant or indexing pipeline.

Recommended next pages:

- [Authentication](/authentication) for credential handling.
- [Pagination](/pagination) for sync jobs and backfills.
- [Errors](/errors) for retry behavior.
- [API keys](/reference/api-keys) for service accounts and machine-to-machine credentials.
- [Webhooks](/reference/webhooks) for signed event delivery.