HaleAI

Developer API

HaleAI HTTP API v1.

Read-only programmatic access to your team's contacts, leads, and deals. Bearer-authenticated, tenant-scoped, paginated. Available on the Team Max tier and above.

Authentication

Every request must include an Authorization: Bearer hk_... header. Mint a token in Settings to API keys. The plaintext token is shown to you once at creation, so copy it to a password manager immediately.

Rate limits: 60 requests in a short burst, 600 per minute sustained, per key. Over-limit requests get a 429 with a Retry-After header.

Response envelopes

List endpoints return { data: [...], pagination: { limit, cursor, nextCursor } }. When nextCursor is non-null, pass it as the next request's cursor to continue paging. Detail endpoints return { data: { ... } }. Errors return { error: { code, message } } with an appropriate HTTP status (400, 401, 404, 429, 500).

Endpoints

  • GET/api/v1/contacts

    Paginated list of contacts in the calling tenant.

    Query parameters

    • limit (1..200): Default 50.
    • cursor (string): From the prior page's nextCursor.
    • source (string): Exact match on contact.source.
    • updatedSince (ISO 8601): Only rows with updatedAt strictly greater than this.
    curl "https://app.alohahale.ai/api/v1/contacts?source=zillow&updatedSince=2026-05-01T00:00:00Z" \
  -H "Authorization: Bearer hk_..."

  • GET/api/v1/contacts/:contactId

    Single contact by id. 404 if not owned by your tenant.

    curl https://app.alohahale.ai/api/v1/contacts/ctk_AbCd \
  -H "Authorization: Bearer hk_..."

  • GET/api/v1/leads/:leadId

    Single lead by id. 404 if not owned by your tenant.

    curl https://app.alohahale.ai/api/v1/leads/ld_AbCd \
  -H "Authorization: Bearer hk_..."

  • GET/api/v1/deals/:dealId

    Single deal by id. 404 if not owned by your tenant.

    curl https://app.alohahale.ai/api/v1/deals/dl_AbCd \
  -H "Authorization: Bearer hk_..."

  • GET/api/v1/leads

    Paginated list of leads. Optional stage filter.

    Query parameters

    • limit (1..200): Default 50.
    • cursor (string): From the prior page's nextCursor.
    • stage (string): new | qualified | nurture | working | won | lost.
    • source (string): Exact match on lead.source.
    • updatedSince (ISO 8601): Only rows with updatedAt strictly greater than this.
    curl "https://app.alohahale.ai/api/v1/leads?stage=working&updatedSince=2026-05-01T00:00:00Z" \
  -H "Authorization: Bearer hk_..."

  • GET/api/v1/deals

    Paginated list of deals. Optional stage filter.

    Query parameters

    • limit (1..200): Default 50.
    • cursor (string): From the prior page's nextCursor.
    • stage (string): opportunity | listing | under_contract | closed | dead.
    • updatedSince (ISO 8601): Only rows with updatedAt strictly greater than this. Deals do not support ?source=.
    curl "https://app.alohahale.ai/api/v1/deals?stage=closed" \
  -H "Authorization: Bearer hk_..."