Connections

A connection links a company to a service that BeeL. works through on its behalf. Today the only service is beel_email, which captures the replies your customers send to the emails of your invoices (see Capture replies by email). More providers will follow, and they will use the same resource.

Connections belong to a company (NIF) and to an environment: the one of the key that creates them. A connection made with a beel_sk_test_ key does nothing in production, and the other way round.

Providers

provider is the service through which a message reaches BeeL. channel is the medium the customer wrote in (EMAIL, WHATSAPP...). They are different fields on purpose: beel_email is an email provider, so its replies have channel: EMAIL, and a future gmail or outlook provider would bring channel: EMAIL too. A reply you register yourself has a channel and no provider (see Register replies from other channels).

There is no endpoint that lists providers. The table above is the catalog, and it is generated from the API contract. A connection you read may have a provider, auth_type or capability you do not know yet: ignore it instead of failing.

Connect a service

POST /v1/companies/{company_id}/connections with the provider and, optionally, its capabilities. Omit them, or send an empty list, to get the default of the provider. Send an Idempotency-Key, as on every write.

curl -X POST "https://app.beel.es/api/v1/companies/$COMPANY_ID/connections" \
  -H "Authorization: Bearer $BEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"provider": "beel_email", "capabilities": ["receive_customer_replies"]}'

The connection is ACTIVE at once and connection.connected is delivered to your webhook endpoints. The response carries the settings of the provider under a property named like it:

{
  "success": true,
  "data": {
    "id": "8c3e1f7a-2b4d-4e6f-9a1c-5d7b3e9f2a41",
    "provider": "beel_email",
    "auth_type": "NONE",
    "capabilities": ["receive_customer_replies"],
    "status": "ACTIVE",
    "created_at": "2026-11-03T08:00:00Z",
    "disconnected_at": null,
    "beel_email": { "reply_domain": "reply.beel.es" }
  }
}

Credentials are never part of a connection.

Read and disconnect

• List the connections of a company, most recent first, with the provider and status filters. Disconnected ones are included.
• Get a connection by id, also when it is DISCONNECTED.
• Disconnect with DELETE /v1/companies/{company_id}/connections/{connection_id}. BeeL. stops doing what the capabilities allowed, the connection stays readable as DISCONNECTED and connection.disconnected is delivered once. Repeating the call answers 204 and delivers nothing.

DISCONNECTED is final. To start again, connect again: that creates a new connection with a new id. For beel_email, see what is captured in Capture replies by email.

Webhooks

Both carry the connection as it is after the change, only reach the endpoints of the account that owns the company, and need the connections:read scope to subscribe to. The envelope and signature are the ones of every webhook.

Related