Public API

Overview

Alphie identifies companies that visit your website and captures or discovers contacts at those companies. The Public API gives you programmatic, read-only access to that data so you can keep your own systems — most commonly a CRM — continuously up to date, without any manual export or import step.

Two resources are available:

• Companies — organizations Alphie has identified visiting your site, along with firmographic data and a fit score against your ideal customer profile.
• Contacts — people captured by your Alphie chat widget and forms, plus people Alphie has discovered at companies it identified.

The API is designed to be polled on a schedule: do an initial backfill, then periodically ask for what's new or changed since your last successful sync. See Incremental Sync for a recommended approach.

This version of the API is read-only — it does not support creating, updating, or deleting data in Alphie.

Base URL

https://app.meetalphie.com/api/public/v1

If your account is served from a dedicated Alphie host, use that host in place of app.meetalphie.com in every example in this document — the path (/api/public/v1/...) stays the same.

Authentication

Requests are authenticated with an API key, issued to you by your Alphie account administrator. API keys look like alph_ followed by 48 hexadecimal characters, for example:

alph_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6

The full key value is shown to your admin exactly once, at creation time. Alphie retains only a one-way hash of it and cannot display it again afterward, so store it securely (e.g. in a secrets manager) as soon as it's created.

Send the key on every request, using either of the following headers:

curl -H "Authorization: Bearer alph_YOUR_KEY" \
  "https://app.meetalphie.com/api/public/v1/companies"

A few things to keep in mind:

• API keys are read-only in this version and are scoped to your Alphie account — a key only ever returns data belonging to the account it was created under.
• An admin can revoke a key at any time. Requests made with a revoked key receive 401 API key revoked (see Errors). Revocation is immediate and cannot be undone — issue a new key if you need to reconnect.

Rate Limits

The API allows 120 requests per minute. Every response includes headers describing your current standing against that limit:

If you exceed the limit, the API responds with 429 Too Many Requests:

{
  "error": "Too many requests",
  "retryAfter": 30
}

retryAfter is the number of seconds to wait before retrying. Back off for at least that long, and consider spacing out your requests (for example, pausing briefly between pages) rather than retrying immediately in a loop.

Pagination

Both list endpoints (GET /companies and GET /contacts) return results in a common envelope:

{
  "data": [ ... ],
  "page": 1,
  "pageSize": 25,
  "total": 214
}

Both endpoints accept the following pagination parameters:

Ordering is stable across pages, so you can safely page from 1 through the last page and get a consistent, non-overlapping view of the result set, even as new data arrives in the background.

Note: page and pageSize values outside their valid range (for example, pageSize=500 or page=0) are rejected with 400 Invalid query parameters — they are not silently clamped to the nearest valid value. Validate these on your side before sending requests.

Incremental Sync

Rather than re-fetching every company and contact on every sync, use the lastSeenSince (companies) and createdSince (contacts) parameters to ask Alphie only for what's changed. A typical integration looks like this:

1. Initial backfill. Starting at page=1 with a large pageSize (up to 100), page through the full result set — increment page until the number of records returned is less than pageSize, or you've retrieved total records. Upsert every record you receive into your CRM, keyed by its id.
2. Record a checkpoint. Once the backfill finishes successfully, store the current time as your lastSyncedAt checkpoint.
3. Poll incrementally. On each subsequent run, call the endpoint with lastSeenSince (companies) or createdSince (contacts) set to your stored checkpoint, minus about one minute. That small overlap protects against clock skew and against records that were still being written at the exact instant of your last checkpoint. Page through the results the same way as the backfill.
4. Upsert by id. Because the overlap window may return a few records you've already synced, always upsert (insert-or-update) by id rather than inserting blindly. This makes each sync run idempotent and safe to retry or re-run.
5. Advance the checkpoint. After a poll completes successfully, move your stored lastSyncedAt forward to the time you started that poll (again, before the one-minute overlap is applied next time).
6. Repeat on an interval that respects the rate limit — every 5–15 minutes is a reasonable starting point for most integrations.

Run the full backfill first. The one-per-person de-duplication described under GET /contacts is evaluated across the records in the response window. In a full backfill (no createdSince) that window is your entire history, so each person appears once. In an incremental poll, a person you already imported as a chat/form contact during the backfill can reappear later as an alphie contact if Alphie discovers them at their company after your checkpoint. Upserting by id keeps this safe; if you require strictly one record per person, de-duplicate by email on your side as well.

GET /companies

Returns companies Alphie has identified visiting your website — via your Alphie widget or forms — ordered by most recent activity first (lastSeenAt descending). Traffic identified only as a bot or generic ISP, with no attributable company, is excluded automatically.

GET /api/public/v1/companies

Query parameters

Response fields

Each object in data has the following shape:

Example request

curl -H "Authorization: Bearer alph_YOUR_KEY" \
  "https://app.meetalphie.com/api/public/v1/companies?pageSize=50&lastSeenSince=2026-07-01T00:00:00Z"

Example response

{
  "data": [
    {
      "id": "8f3a1c2e-9b7d-4f10-a2c4-6e8d0b2f4a61",
      "domain": "brightloopsystems.com",
      "name": "BrightLoop Systems",
      "website": "https://www.brightloopsystems.com",
      "description": "Cloud-based inventory management software for mid-market retailers.",
      "industry": "Software",
      "employeeCount": "51-200",
      "annualRevenue": "$10M-$25M",
      "foundedYear": "2015",
      "linkedinUrl": "https://www.linkedin.com/company/brightloop-systems",
      "city": "Austin",
      "country": "United States",
      "icpScore": 87,
      "icpFit": "Strong Fit",
      "sessions": 14,
      "firstSeenAt": "2026-06-02T14:22:31Z",
      "lastSeenAt": "2026-07-21T09:47:03Z"
    },
    {
      "id": "2b6e9d4a-1f5c-4873-b0e2-7c31da95f2c8",
      "domain": "nordvale-consulting.eu",
      "name": "Nordvale Consulting",
      "website": "https://www.nordvale-consulting.eu",
      "description": null,
      "industry": "Professional Services",
      "employeeCount": "11-50",
      "annualRevenue": null,
      "foundedYear": null,
      "linkedinUrl": "https://www.linkedin.com/company/nordvale-consulting",
      "city": "Amsterdam",
      "country": "Netherlands",
      "icpScore": 54,
      "icpFit": "Possible Fit",
      "sessions": 3,
      "firstSeenAt": "2026-07-10T08:03:12Z",
      "lastSeenAt": "2026-07-20T16:58:44Z"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 214
}

GET /contacts

Returns people captured by your Alphie chat widget and forms, plus contacts Alphie has discovered at companies it has identified, ordered newest first (createdAt descending).

GET /api/public/v1/contacts

Query parameters

source values:

Dedupe note: if the same person both submits a chat or form message and is separately discovered by Alphie at their company, they appear only once in this endpoint — as the chat or form record — never duplicated as a separate alphie record.

Response fields

Each object in data has the following shape:

The nested company object, when present, has the following shape:

Example request

curl -H "Authorization: Bearer alph_YOUR_KEY" \
  "https://app.meetalphie.com/api/public/v1/contacts?source=alphie&pageSize=50"

Example response

The example below shows one contact from each source (a request without a source filter, i.e. source=all, would return a mix like this):

{
  "data": [
    {
      "id": "1a4f7c2e-8b3d-4961-9c5e-d40e2a718b36",
      "source": "chat",
      "fullName": "Maria Chen",
      "firstName": null,
      "lastName": null,
      "email": "maria.chen@brightloopsystems.com",
      "phone": "+1-512-555-0148",
      "jobTitle": null,
      "linkedinUrl": null,
      "message": "Hi, we're looking for a solution to sync inventory across 3 warehouses. Can you tell me more about pricing?",
      "status": "QUALIFIED",
      "company": {
        "id": "8f3a1c2e-9b7d-4f10-a2c4-6e8d0b2f4a61",
        "name": "BrightLoop Systems",
        "domain": "brightloopsystems.com",
        "website": "https://www.brightloopsystems.com"
      },
      "createdAt": "2026-07-21T09:50:12Z"
    },
    {
      "id": "9d2e5b8a-4f1c-4036-8d7b-64c1e0af5923",
      "source": "form",
      "fullName": "Tobias Reyes",
      "firstName": null,
      "lastName": null,
      "email": "tobias.reyes@nordvale-consulting.eu",
      "phone": null,
      "jobTitle": null,
      "linkedinUrl": null,
      "message": "Requesting a demo for our operations team.",
      "status": "NEW",
      "company": {
        "id": "2b6e9d4a-1f5c-4873-b0e2-7c31da95f2c8",
        "name": "Nordvale Consulting",
        "domain": "nordvale-consulting.eu",
        "website": "https://www.nordvale-consulting.eu"
      },
      "createdAt": "2026-07-20T17:02:09Z"
    },
    {
      "id": "5f8c1a3e-9d7b-4264-a1c9-3be07f61d245",
      "source": "alphie",
      "fullName": "Priya Natarajan",
      "firstName": "Priya",
      "lastName": "Natarajan",
      "email": "priya.natarajan@brightloopsystems.com",
      "phone": null,
      "jobTitle": "VP of Operations",
      "linkedinUrl": "https://www.linkedin.com/in/priyanatarajan",
      "message": null,
      "status": null,
      "company": {
        "id": "8f3a1c2e-9b7d-4f10-a2c4-6e8d0b2f4a61",
        "name": "BrightLoop Systems",
        "domain": "brightloopsystems.com",
        "website": "https://www.brightloopsystems.com"
      },
      "createdAt": "2026-07-19T11:14:55Z"
    }
  ],
  "page": 1,
  "pageSize": 25,
  "total": 58
}

Errors

All error responses are JSON objects with an error field. Some also include additional detail specific to the error.

Versioning

The current version of the API is v1, identified by the /v1 segment in the base URL. Within v1, changes are additive only: new optional query parameters and new response fields may be introduced over time, but existing fields will not be removed, renamed, or repurposed. Integrate defensively — parse responses leniently and ignore any fields you don't recognize — so future additions never break your sync.