Get a company
Scopecompanies:readReturns the identity and activation state of a company: 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
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.
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": "The invoice must have at least one line",
"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 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. **Paginated** with the usual `page`/`limit`, and the usual defaults: without them you get the stats of the first 20 companies, not of all of them. One row per company, over the same universe and in the same order as `GET /v1/accounts/{account_id}/companies` — `search` included — so asking both with the same `page`, `limit` and `search` lines the two responses up company by company.
Update a company PATCH
Updates the editable fields of a company; the set is the one `UpdateCompanyRequest` declares. - **Immutable fields:** `nif`, `entity_type` and `legal_form`, once set. Sending one of them with a different value answers `422` with a code that names the field; sending the value it already has is not a change. - **`legal_name`:** changing it requires the NIF to pass an AEAT census re-validation. For a legal entity (`LEGAL_ENTITY`) the census identifies the company by its NIF alone: the name is not verified, so the name sent cannot make it fail. For an `INDIVIDUAL` the name must match the one the census holds for that NIF. - **Census not answering:** if the AEAT census cannot be reached, the change is not rejected. The response is `200` with the new `legal_name` stored, and BeeL repeats the census check in the background. The outcome of that check is not part of this resource: no field of `CompanyData` carries it. To know what the census says about a NIF and a name, ask `POST /v1/nif/validate`. - **Addresses:** a Spanish postal code (`country_code` omitted or `ES`) must have 5 digits, in `address` and in `legal_representative.address`; otherwise `422 POSTAL_CODE_INVALID_ES`. Other countries' postal codes are free-form. ## 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`.