Connect a service
Scopeconnections:writeConnects a service that needs no authorization, with the capabilities you choose or the
provider's default. The connection is ACTIVE at once and connection.connected is delivered.
Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key
short of the scope an operation needs is answered 403. The scope an operation requires
is shown next to its title, and the full catalogue lives in the Scopes reference.
Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.
In: header
Path Parameters
Unique identifier (UUID) of the company the operation acts on: its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the BeeL-Active-Company header plays no part. A company you do not reach answers 403, and so does a company that does not exist, so the existence of a company in another account is never disclosed.
uuidHeader Parameters
Idempotency key to prevent duplicates in sensitive operations.
- Any unique client-generated string (e.g. an order id). A UUID also works but is not required
- Allowed characters: letters, digits,
_and-(max 255 chars) - Retrying with the same key replays the first response when it was a success (2xx) or a
server error (5xx): same status and body, plus the header
Idempotency-Replay: true. After a 5xx other than 503, check whether the operation took effect before retrying with a new key - After a
503, retry first with the same key. If the response carriesIdempotency-Replay: true, the operation may have taken effect: check the resource before using a new key. Without that header, the retry runs the operation once - A 4xx is not stored: the key is released, so the corrected request can reuse it
- Stored responses expire 24 hours after processing
The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.
| Status | Code | When |
|---|---|---|
400 | INVALID_IDEMPOTENCY_KEY | The key breaks the format rules above. |
409 | IDEMPOTENCY_KEY_PROCESSING | The first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key. |
409 | IDEMPOTENCY_KEY_MISMATCH | The key was already used with a different body. Use a new key. |
^[a-zA-Z0-9_-]+$length <= 255The service the connection is with. More providers will be added: ignore a connection whose provider you do not know.
beel_email: replies to the email of each invoice, received at an address of BeeL. Supportsreceive_customer_replies; one per company and environment.
What BeeL. may do through the connection. Omit it, or send it empty, to get the
provider's default (receive_customer_replies for beel_email).
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/connections" \ -H "Content-Type: application/json" \ -d '{ "provider": "beel_email", "capabilities": [ "receive_customer_replies" ] }'{
"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"
}
}
}{
"success": false,
"error": {
"code": "BAD_REQUEST",
"message": "Invalid request"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication is required to access this resource"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The provided data is not valid",
"details": {
"field": "specific error message"
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
},
"type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
"title": "INVOICE_NO_LINES",
"detail": "The invoice must have at least one line",
"instance": "/v1/invoices/abc-123"
}{
"success": false,
"error": {
"code": "CONNECTION_DUPLICATE",
"message": "The company already has a connection with this provider.",
"details": {
"connection_id": "8c3e1f7a-2b4d-4e6f-9a1c-5d7b3e9f2a41",
"provider": "beel_email"
}
},
"meta": {
"timestamp": "2026-11-03T08:00:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "CONNECTION_REPLY_TO_REQUIRED",
"message": "Set the email of the company before connecting the reply capture by email."
},
"meta": {
"timestamp": "2026-11-03T08:00:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Please try again in 60 seconds."
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "INTERNAL_ERROR",
"message": "Internal server error"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type: text/plain. Supported: application/json"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}Revoke an invitation DELETE
Revokes a `PENDING` invitation, so its acceptance link stops working. - **Already resolved:** an `ACCEPTED`, `REVOKED` or `EXPIRED` invitation cannot be revoked, and answers `404` without disclosing which of the three it is. - **History:** revoking does not remove the invitation from the list.
List connections GET
Returns the connections of the company in the environment of the credential, most recent first, including the disconnected ones.