List the companies of an account
Scopecompanies:listReturns the companies (NIFs) belonging to the account in the path, ordered with the primary company first. An account with no companies yet returns an empty list rather than an error.
search: filters case-insensitively on NIF, legal name and trade name.include=readiness: adds each company's issuing-readiness block.pagination: present only when the request is paginated — that is, when any ofpage,limitorsearchis sent. It is omitted for the full list.- Series: not part of this response. Read them from
GET /v1/companies/{company_id}/series.
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
Your own account, or an account you provisioned. It — not the credential — decides which account the operation acts on; a 403 is returned when you do not reach it, the same response an account that does not exist gets.
uuidQuery Parameters
Page number, starting at 1. The response echoes it back as pagination.current_page.
11 <= valueHow many items to return per page. The response echoes it back as pagination.items_per_page.
201 <= value <= 100Case-insensitive filter on NIF, legal name or trade name. Blank/omitted returns all.
Include derived data. readiness adds each company's issuing-readiness status.
"readiness"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://app.beel.es/api/v1/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08/companies"{
"success": true,
"data": {
"companies": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"access_level": "NONE",
"nif": "string",
"legal_name": "string",
"trade_name": "string",
"entity_type": "INDIVIDUAL",
"is_primary": true,
"verifactu_status": "NOT_CONFIGURED",
"environment": "PROD",
"in_prod": true,
"in_test": true,
"aeat_environment": "PROD",
"account_state": "TEST_ONLY",
"address": {
"street": "string",
"number": "string",
"floor": "string",
"door": "string",
"postal_code": "string",
"city": "string",
"province": "string",
"country": "string",
"country_code": "string"
},
"legal_form": "string",
"legal_representative": {
"full_name": "María García López",
"nif": "12345678A",
"address": {
"street": "Calle Mayor, 123",
"number": "123",
"floor": "2º A",
"door": "A",
"postal_code": "28001",
"city": "Madrid",
"province": "Madrid",
"country": "España",
"country_code": "ES"
}
},
"phone": "+34 612 345 678",
"email": "user@example.com",
"website": "string",
"logo_url": "string",
"additional_info": "string",
"default_iban": "ES1234567890123456789012",
"default_swift": "ABCDESMMXXX",
"account_holder": "string",
"iae": "string",
"activity_start_date": "2019-08-24",
"default_payment_term": 365,
"invoice_template_type": "MODERN_TABLE",
"invoice_accent_color": "#fc481d",
"invoice_language": "es",
"email_language": "es",
"default_irpf_rate": 0,
"created_at": "2019-08-24T14:15:22Z",
"readiness": {
"ready": true,
"blockers": [
"COMPANY_HAS_NO_NIF"
],
"verifactu": {
"ready": true,
"blockers": [
"ENV_MISMATCH"
]
}
}
}
],
"pagination": {
"current_page": 1,
"total_pages": 5,
"total_items": 87,
"items_per_page": 20,
"has_next": true,
"has_previous": true
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"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": "La factura debe tener al menos una línea",
"instance": "/v1/invoices/abc-123"
}{
"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"
}
}Create a company POST
Creates a company (NIF) under the account the request resolves to. The NIF is registered in the name of that account's holder, never in the name of the caller. - **`activate`:** unless it is `false`, the company is switched on in `aeat_environment` and its three default invoice series (ordinary, simplified, corrective) are seeded there. This endpoint never switches an existing company on: that is `POST /v1/companies/{company_id}/activations`. - **`numbering`:** decides the code, format, counter reset and starting number those series are born with. Only accepted when the request activates the company. - **Billing:** no charge is ever started here. Creating a production NIF on an account without billing is rejected with `402`, and no checkout is opened. - **Duplicates:** a NIF that already exists in the account is rejected with `409`, and the response carries the existing `error.details.company_id`.
Get invoice stats per company GET
Returns, for each company (NIF) of the account, how many fiscal documents it has issued and when it last issued one. - **`invoice_count`:** drafts, scheduled invoices and proformas are not counted; a rectifying invoice counts as a document of its own, and a voided invoice counts only when a live rectifying invoice compensates it. - **`last_invoice_at`:** issue date of the most recent document in that same set, or `null` when there is none. - **Not a cursor:** the count is not monotonic — voiding an uncompensated invoice lowers it and moves `last_invoice_at` backwards — so do not synchronise on it.