Get a company
Scopecompanies:readReturns the identity and activation state of a company (NIF): its fiscal data, whether it is switched on in Test and in Live, and its VeriFactu registration state.
It also returns every field PATCH /v1/companies/{company_id} accepts — contact
details, legal representative, bank details, IAE, activity start date, payment term and
the rendering block — so what was written can be read back without keeping a copy of it.
A field never set comes back absent: that means "nothing stored", not "hidden".
Its invoice series are 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
NIF (company) the operation acts on. 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 NIF you do not reach answers 403, and so does a NIF that does not exist, so the existence of a NIF in another account is never disclosed.
uuidResponse Body
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"{
"success": true,
"data": {
"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"
]
}
}
},
"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"
}
}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.
Update a company PATCH
Updates the editable fields of a company (NIF); the set is the one `UpdateCompanyRequest` declares. - **Immutable fields:** `nif`, `entity_type` and `legal_form`, once set. - **`legal_name`:** changing it requires the NIF to pass an AEAT census re-validation — which for a company checks the CIF only, so it cannot fail because of the name sent. ## Test credentials on a Live company Once the company is activated in Live, a test credential may only write the fields that affect how the invoice looks: `logo_url`, `invoice_accent_color`, `invoice_template_type`, `invoice_language`, `email_language` and `additional_info`. Any other field describes the real business — fiscal address, legal representative, bank details, contact data, IAE, activity start date, payment term — and answers `422 FISCAL_IDENTITY_LIVE_ONLY` from Test, since the company is a single record shared by both modes. A company not activated in Live accepts the whole body from Test, and sending a field its current value is never a change. ## What comes back The `200` returns `CompanyData` with **every field this request accepts**, under the same name and the same type — so the response is the confirmation of what was stored, and a later `GET` says the same. A field you never set comes back absent, which means "nothing stored", not "hidden". Two things live outside this body and keep their own reads: the invoice series (`GET /v1/companies/{company_id}/series`) and the rendering block, which is also served on its own by `GET /v1/companies/{company_id}/invoice-customization`.