NewConnections and customer replies to invoices
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Invoice Replies

List invoice replies

Scopeinvoice-replies:read

Returns the replies of the customers of the company about its invoices, on every channel, most recent first, each with a masked excerpt. Read one with its text in GET .../invoice-replies/{reply_id}.

GET
/v1/companies/{company_id}/invoice-replies

Authorization

AuthorizationBearer <token>

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

company_idstring

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.

Formatuuid

Query Parameters

page?integer

Page number, starting at 1. The response echoes it back as pagination.current_page.

Default1
Range1 <= value
limit?integer

How many items to return per page. The response echoes it back as pagination.items_per_page.

Default20
Range1 <= value <= 100
invoice_id?string

Keep only the replies about this invoice.

Formatuuid
connection_id?string

Keep only the replies that arrived through this connection. The replies registered with POST .../invoice-replies have no connection, so they never match.

Formatuuid
customer_id?string

Keep only the replies about invoices of this customer.

Formatuuid
channel?array<InvoiceReplyChannel>

Keep only the replies received on these channels. Accepts a comma-separated list, for example channel=WHATSAPP,SMS. A value BeeL. does not know matches nothing.

from?string

Keep only the replies received at or after this instant.

Formatdate-time
to?string

Keep only the replies received at or before this instant.

Formatdate-time
sort_order?string
Value in"asc" | "desc"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoice-replies"
{
  "success": true,
  "data": {
    "replies": [
      {
        "id": "3f0c9a1e-6b2d-4c8f-a1e5-7d9b0c2e4f61",
        "channel": "EMAIL",
        "authenticated_by": "REPLY_TOKEN",
        "connection_id": "8c3e1f7a-2b4d-4e6f-9a1c-5d7b3e9f2a41",
        "invoice_id": "b71d5e2a-9c3f-4a7b-8e10-2f6d4c8a9b13",
        "invoice_number": "F2026-0142",
        "customer_id": "7a2c9e14-3b5d-4f6a-8c0e-1d2b3a4c5e6f",
        "status": "RECEIVED",
        "received_at": "2026-11-03T09:12:44Z",
        "sender": {
          "address": "[EMAIL]"
        },
        "subject": "RE: Factura F2026-0142",
        "excerpt": "Hola, el CIF que aparece no es el nuestro, es [NIF]. ¿Podéis corregirla?",
        "attachments": []
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 1,
      "total_items": 1,
      "items_per_page": 20,
      "has_next": false,
      "has_previous": false
    }
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The parameter 'invoice_id' has an invalid type. Expected: UUID.",
    "details": {
      "field": "invoice_id",
      "invalid_value": "deliveries",
      "expected_format": "UUID"
    }
  },
  "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": "VALIDATION_ERROR",
    "message": "Validation constraint violation.",
    "details": {
      "limit": "must be greater than or equal to 1"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30: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"
  }
}

Get an attachment of an invoice reply GET

Returns the attachment with a temporary `download_url` for its file. BeeL. does not store the file: the link is requested when you call this operation and stays valid for about an hour, so call it again for a fresh one rather than keeping it. `download_url` and `download_url_expires_at` are `null` when there is no file to download: the attachment was registered with `POST .../invoice-replies`, or its file is no longer available (see `file_expires_at`).

List recurring invoices GET

Lists the recurring invoice templates of this company, with filters and pagination. Only the templates of the company in the path are returned.