> ## Documentation Index > Fetch the complete documentation index at: https://docs.melso.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Melso MCP: https://mcp.melso.ai/mcp (OAuth; one company per connection). Documentation-search MCP: https://docs.melso.ai/mcp; it does not act on customer accounts. > > Use the live tool list and respect company membership. Ask the person to approve the exact invoice or tax return version in the signed-in app. Melso's professionals prepare and file included returns after approval; an AI assistant does not file. A prepared file or an approval is not evidence of filing: only the AEAT's reference and receipt are. Keep credentials out of chat and logs. # Create a company > Adds an autónomo (freelancer) or an empresa (company) to your partner account, with its owner and as much of its fiscal profile as you know. **Preview.** A contract we are building with design partners. It is not callable yet, and fields can still change. See [Availability](/api/availability). The owner is the person who approves invoices and returns. Send `setup_request` when the company is not registered yet: Melso's professionals register the autónomo (036 or 037 and RETA) or incorporate the company as a case. ## OpenAPI ````yaml api/openapi.yaml POST /companies openapi: 3.1.0 info: title: Melso API version: 1.0.0-preview summary: Spanish tax and labour compliance for the companies on your platform. description: | The Melso API lets an HR, payroll, banking or ERP platform run the Spanish tax and labour obligations of the companies it serves: invoices, books, tax returns, Social Security and employment notifications. Melso calculates and prepares. A person at the company approves the exact version. Melso's professionals file under the company's representation, and the filing is proven only by the administration's reference and receipt. Every operation states its availability in `x-melso-status`: - `live`: Melso runs this capability in production today. Partner keys reach it once a partner account is enabled. - `preview`: a contract proposed to design partners. Not callable yet. `x-melso-actor: person` marks a decision a signed-in person makes in Melso; a partner sends them the approval link instead. contact: name: Melso partnerships email: hello@melso.ai url: https://docs.melso.ai/api/overview servers: - url: https://api.melso.ai/v1 description: API. Keys and access are issued per partner. security: - partnerKey: [] tags: - name: Companies description: The companies you operate for, their fiscal profile and hosted onboarding. - name: Mandates description: >- The company's representation of Melso before the AEAT, the TGSS and the SEPE. - name: Webhook endpoints description: Where Melso sends signed events about your companies. - name: Invoicing setup description: Registration of the company as a VERI*FACTU or TicketBAI invoice issuer. - name: Customers description: The company's invoice customers. - name: Invoices description: >- Drafts, approval, legal registration, delivery and payment of the company's invoices. - name: Expenses description: >- Purchase invoices and receipts, with their AEAT category and deductibility. - name: Income description: Income invoiced outside Melso. - name: Documents description: >- Files the company gives Melso, and Melso's structured reading of an invoice or receipt. - name: Banking description: >- Bank accounts, movements, statements and reconciliation with invoices and expenses. - name: Accounting description: Journal, imported books and the company's financial statements. - name: Tax calendar description: The forms the company must file, with their periods and deadlines. - name: Tax returns description: The returns Melso calculates, their approval and their filing. - name: Corporate tax description: The year's corporate tax (modelo 200) and its instalments (modelo 202). - name: Tax estimates description: What the company should set aside for taxes, as of today. - name: Cases description: Gestiones, the procedures Melso's professionals carry out for the company. - name: Administration notifications description: Electronic notifications from the administration to the company. - name: Certificates description: >- Official certificates such as being up to date with the AEAT or the Social Security. - name: Employees description: The people the company employs. - name: Payroll runs description: >- The payroll results your platform calculated, for Melso to settle and declare. - name: Social Security description: >- Affiliation (altas, bajas and variaciones) and monthly contribution settlements. - name: Employment notifications description: >- Contrat@ contract notifications and Certific@2 company certificates to the SEPE. paths: /companies: post: tags: - Companies summary: Create a company description: > Adds an autónomo (`freelancer`) or an empresa (`company`) to your partner account, with its owner and as much of its fiscal profile as you know. The owner is the person who approves invoices and returns. Send `setup_request` when the company is not registered yet: Melso's professionals register the autónomo (036 or 037 and RETA) or incorporate the company as a case. operationId: createCompany parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CompanyCreate' example: kind: company name: Talleres Ebro external_id: cus_48213 owner: name: Lucía Martín Pérez email: lucia@example.com locale: es fiscal_profile: tax_id: B12345674 legal_name: Talleres Ebro S.L. address: Calle Mayor 1 postal_code: '50001' city: Zaragoza activity_description: Reparación de vehículos vat_regime: general services: - invoicing - tax_returns - payroll responses: '201': description: The company. `missing` lists what its fiscal profile still needs. content: application/json: schema: $ref: '#/components/schemas/Company' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '409': $ref: '#/components/responses/Conflict' components: parameters: IdempotencyKey: name: Idempotency-Key in: header description: >- A unique key, such as a UUID, that makes a retried create safe. Reusing a key with a different body is refused. schema: type: string maxLength: 255 schemas: CompanyCreate: type: object required: - kind - name - owner additionalProperties: false properties: kind: $ref: '#/components/schemas/CompanyKind' name: type: string external_id: type: string owner: type: object required: - name - email description: The person who approves the company's invoices and returns. properties: name: type: string email: type: string format: email phone: type: string locale: type: string enum: - es - ca - en fiscal_profile: $ref: '#/components/schemas/FiscalProfileInput' setup_request: type: string enum: - none - register_autonomo - incorporate_sl default: none description: >- Ask Melso's professionals to register the autónomo or incorporate the company. services: type: array items: type: string enum: - invoicing - bookkeeping - tax_returns - payroll Company: type: object required: - id - name - kind - onboarded - created_at properties: id: type: string format: uuid name: type: string kind: $ref: '#/components/schemas/CompanyKind' onboarded: type: boolean description: Whether the company's setup is finished. external_id: type: - string - 'null' description: Preview. Your ID for the company. missing: type: array description: Preview. What the fiscal profile still needs, as in `tax_missing`. items: type: string created_at: type: string format: date-time updated_at: type: string format: date-time CompanyKind: type: string enum: - freelancer - company description: '`freelancer` for an autónomo, `company` for an empresa.' FiscalProfileInput: allOf: - $ref: '#/components/schemas/FiscalProfileFields' - type: object properties: clear: type: array description: Fields to empty. items: type: string Error: type: object required: - error properties: error: type: string description: What went wrong, for a person to read. code: type: string description: >- A stable code to branch on, such as `invoicing_not_ready` or `version_conflict`. request_id: type: string description: Quote it when you contact Melso. FiscalProfileFields: type: object properties: tax_id: type: string description: >- DNI or NIE for an autónomo, CIF for an empresa, with a valid check character. legal_name: type: string maxLength: 300 trade_name: type: string maxLength: 300 address: type: string maxLength: 300 postal_code: type: string pattern: ^[0-9]{5}$ description: Fills in `province` and `tax_territory`. city: type: string maxLength: 300 province: type: string maxLength: 300 tax_territory: $ref: '#/components/schemas/TaxTerritory' vat_regime: type: string enum: - general - recargo_equivalencia - simplificado - reagp - exento - igic_general - igic_simplificado - igic_repep - ipsi description: Must fit the tax territory. activity_type: type: string enum: - profesional - empresarial description: An empresa is always `empresarial`. activity_description: type: string maxLength: 300 iae_code: type: string pattern: ^[0-9]{1,4}(\.[0-9]{1,2})?$ registration_status: type: string enum: - alta - pendiente description: '`pendiente` while the autónomo is not registered yet.' registered_on: type: string description: '`YYYY-MM` or `YYYY-MM-DD`, not in the future.' irpf_method: type: string enum: - directa_simplificada - directa_normal - modulos description: Autónomos only. irpf_retention_rate: type: number minimum: 0 maximum: 100 description: Autónomos only. eu_operator: type: boolean description: Registered in the ROI for intra-community operations. vat_sii: type: boolean description: Keeps its VAT books through the SII. vat_redeme: type: boolean description: Registered for monthly VAT refunds. is_large_company: type: boolean description: Gran empresa filing VAT and withholdings monthly.: null client_types: type: array minItems: 1 items: type: string enum: - es_business - es_individual - eu_business - non_eu_business invoice_series: type: string maxLength: 40 next_invoice_number: type: integer minimum: 1 maximum: 1000000000 iban: type: string description: Returned masked. TaxTerritory: type: string enum: - comun - alava - bizkaia - gipuzkoa - navarra - canarias - ceuta - melilla responses: BadRequest: description: >- The request is malformed or a field is invalid. Unknown fields are refused. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: lines[0].vat_rate must be 21, 10, 4 or 0 code: invalid_invoice request_id: req_01JAB3K9X2 Unauthorized: description: The key is missing, revoked or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid token code: unauthorized request_id: req_01JAB3K9X2 Conflict: description: >- The object changed or is not in a state that allows this. Read it again and decide. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: The tax return changed or is not ready for approval code: version_conflict request_id: req_01JAB3K9X2 securitySchemes: partnerKey: type: http scheme: bearer description: | Your partner secret key, `mk_live_…` for real companies or `mk_test_…` for test companies. Keep it on your servers. See [Authentication](/api/authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.