{"openapi":"3.0.0","info":{"title":"Companies","version":"1.0.0","description":"The companies endpoint in the Nalanda API allows you to manage company information within your system. This includes creating, updating, retrieving, and deleting company records — essential for platforms that handle multiple organizations or clients.\n\nA key feature of this API is the use of the tax ID as the primary identifier for all operations. For Spanish CIFs, the tax ID can be used without the country code (e.g., C65434870). However, for companies based in other countries, the tax ID must include the country code to properly identify the origin — for example, ZW307710350 for a Zimbabwean company.\n\nThe format for these country codes follows the ISO 3166-1 alpha-2 standard, ensuring consistency across international identifiers. This distinction is crucial for maintaining accurate and compliant company records across different jurisdictions."},"servers":[{"url":"https://api.nalandaglobal.com/api","description":"Prod"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Company":{"type":"object","x-examples":{"Spanish tax ids":{"id":"01GSSY8TF6G8NDNZAW0CP5JPCW","tax_id":"E60448966","company_name":"Asdf","phone":"654789321","type_description":"General"},"Other tax ids":{"tax_id":"01GSSY8TF6G8NDNZAW0CP5JPCW","company_name":"MX60472461","phone":"654321789","type_description":"General"}},"properties":{"ulid":{"type":"string","description":"Ulid (unique identifier) of the company","example":"01HSX4RKRF1HJCPKGJKQCKHM28","readOnly":true},"tax_id":{"type":"string","description":"Tax id of the company"},"company_name":{"type":"string","maxLength":100,"x-stoplight":{"id":"ak8ijx25dwxld"},"description":"Company name"},"phone":{"type":"string","maxLength":40,"description":"Company phone number"},"type_description":{"x-stoplight":{"id":"fuzlycf1w1rmf"},"description":"Company Type","type":"string","readOnly":true}},"required":["tax_id","company_name","email","phone"]},"CompanyProfile":{"title":"CompanyProfile","x-stoplight":{"id":"zt7k1prof09ax"},"allOf":[{"$ref":"#/components/schemas/Company"},{"type":"object","properties":{"self_employed":{"type":"boolean","x-stoplight":{"id":"slf1mpy0dxr9a"},"description":"Whether the company is self-employed (autónomo). Structured, programmatically decidable flag derived from the company's legal nature. Omitted when it cannot be resolved.","readOnly":true},"trading_name":{"type":"string","x-stoplight":{"id":"ybd9p4vut04a5"},"description":"The company's trading (commercial) name. Omitted when not set."},"fiscal_address_country":{"type":"string","x-stoplight":{"id":"gshdm293dmrrh"},"description":"Country of the company's registered fiscal address, in English (e.g. \"Spain\")."},"tax_residence_country":{"type":"string","x-stoplight":{"id":"gdt3og4ia8qgr"},"description":"Country of tax residence, in English. Currently mirrors the fiscal address country."},"community_and_province":{"type":"string","x-stoplight":{"id":"nac4y1elwp2cs"},"description":"Autonomous community and province of the fiscal address, in Spanish, formatted as \"Community - Province\" (e.g. \"Andalucía - Cádiz\")."},"fiscal_address":{"type":"string","x-stoplight":{"id":"gh2vu5qio29aq"},"description":"First line (street) of the company's fiscal address."},"postal_code":{"type":"string","x-stoplight":{"id":"1pf4ru39ogaqt"},"description":"Postal code of the fiscal address."},"web_address":{"type":"string","x-stoplight":{"id":"ctaxeslfia9s1"},"description":"Company website URL. Omitted when none is registered."}}}],"description":"Enriched company profile returned exclusively by GET /companies/{tax_id}. Extends the slim Company with supplier-profile attributes. Fields that cannot be resolved during enrichment are omitted from the response, so consumers must treat every added field as optional."},"Zone":{"title":"Zone","x-stoplight":{"id":"ad3pbxyum1nmz"},"type":"object","description":"Zone of the company","properties":{"code":{"type":"string","x-stoplight":{"id":"0yt6aboixllja"},"example":"11W1","description":"Code of the Zone"},"description":{"type":"string","x-stoplight":{"id":"u2x04mmlu2c3f"},"example":"GAL-Galicia","description":"Description of the Zone","readOnly":true}},"required":["code"]},"CIF":{"title":"CIF","x-stoplight":{"id":"mcbbnrskiss0q"},"type":"object","description":"Cif model","properties":{"value":{"type":"string","x-stoplight":{"id":"5l1694u1ckcr2"},"description":"Raw value of Cif/Tax Id","example":"12345678Z"},"type":{"x-stoplight":{"id":"cqj9937fj5bew"},"enum":["INTERNACIONAL","UTE","EMPRESA","AUTONOMO"]}}},"CCC":{"title":"CCC","x-stoplight":{"id":"rp9i4z90wv7to"},"type":"object","description":"Código cuenta cotización model","properties":{"rawValue":{"type":"string","x-stoplight":{"id":"wzuvhnxwjkna7"},"description":"ccc value","example":"0111 28167037226"},"valid":{"type":"boolean","x-stoplight":{"id":"wsz501lz5gnbk"},"description":"Whether the value is valid or not"}}},"SocialSecurityResponse":{"title":"SocialSecurityResponse","x-stoplight":{"id":"v09nldsjic0fg"},"type":"object","properties":{"cifProveedor":{"$ref":"#/components/schemas/CIF"},"cccProveedor":{"$ref":"#/components/schemas/CCC"},"cifConstructor":{"$ref":"#/components/schemas/CIF"},"cccConstructor":{"$ref":"#/components/schemas/CCC"},"razonSocialConstructor":{"type":"string","x-stoplight":{"id":"3kx1r74wy8le0"}},"ared":{"type":"string","x-stoplight":{"id":"x1xt9kanp31ty"}},"cccEmpresa":{"$ref":"#/components/schemas/CCC"}},"description":"Social Security response"},"REAResponse":{"title":"REAResponse","x-stoplight":{"id":"b2hy7axce2exa"},"type":"object","description":"REA Response","properties":{"partyId":{"type":"string","x-stoplight":{"id":"q6c7iumxn9yeu"},"example":"270745"},"cif":{"type":"string","x-stoplight":{"id":"ngl5by88du0x7"},"example":"A30745772"},"tipoHuella":{"type":"string","x-stoplight":{"id":"ax3id662419t6"},"example":"CIF"},"cifHuella":{"type":"string","x-stoplight":{"id":"qq22kwgbrblxf"},"example":"A30745772"},"fechaRevision":{"type":"string","x-stoplight":{"id":"4jluibuu476fu"},"example":"17/01/2021","format":"date"}}}},"responses":{"500-Internal-Server-Error":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"./Error.yaml"}}}},"409-Conflict":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"./Error.yaml"}}}},"404-Not-Found":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"./Error.yaml"}}}},"403-Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"./Error.yaml"}}}},"401-Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"./Error.yaml"}}}},"400-Bad-Request":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"./Error.yaml"},"examples":{}}}},"406-Not-Acceptable":{"description":"Not Acceptable","content":{"application/json":{"schema":{"$ref":"./Error.yaml"},"examples":{}}}}},"parameters":{"accept":{"name":"Accept","in":"header","required":true,"schema":{"type":"string"},"description":"application/vnd.nalanda.api-v1.0+json"},"id":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"id of ulid type"},"tax_id":{"name":"tax_id","in":"path","required":true,"schema":{"type":"string"},"description":"The tax id of the company"},"status":{"name":"status","in":"query","schema":{"type":"string","enum":["all","active","inactive"],"default":"all"},"description":"Status of the company"},"page":{"name":"page","in":"query","required":false,"schema":{"type":"number"},"description":"Number of the current page"},"size":{"name":"size","in":"query","required":false,"schema":{"type":"number"},"description":"Size for every page"},"sort":{"name":"sort","in":"query","required":false,"schema":{"type":"string"},"description":"Sort by field"},"contentType":{"name":"Content-Type","in":"header","required":false,"schema":{"type":"string"},"description":"application/json"}}},"paths":{"/companies":{"post":{"summary":"Create company","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"security":[{"bearerAuth":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"},"examples":{"Example 1":{"value":{"tax_id":"12345678Y","company_name":"My Company","phone":"6576542323"}}}},"application/xml":{"schema":{"type":"object","properties":{}}}},"headers":{"Location":{"schema":{"type":"string"},"description":"The location url to get the company created"}}},"400":{"$ref":"#/components/responses/400-Bad-Request"},"401":{"$ref":"#/components/responses/401-Unauthorized"},"403":{"$ref":"#/components/responses/403-Forbidden"},"406":{"$ref":"#/components/responses/406-Not-Acceptable"},"409":{"$ref":"#/components/responses/409-Conflict"}},"description":"API operation to create a company","operationId":"createCompany","parameters":[{"$ref":"#/components/parameters/accept"},{"schema":{"type":"string"},"in":"header","name":"Content-Type","description":"application/json"}]},"parameters":[]},"/companies/{tax_id}":{"put":{"summary":"Update company","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}},"application/xml":{"schema":{"type":"object","properties":{}}}},"headers":{}},"400":{"$ref":"#/components/responses/400-Bad-Request"},"401":{"$ref":"#/components/responses/401-Unauthorized"},"403":{"$ref":"#/components/responses/403-Forbidden"},"406":{"$ref":"#/components/responses/406-Not-Acceptable"}},"description":"<!-- BEGIN supported-platforms -->\n<!-- theme: none -->\n>#### Supported Platforms: NATIONAL / INTERNATIONAL\n<!-- END supported-platforms -->\n\nAPI operation to update a company","operationId":"updateCompany","parameters":[{"$ref":"#/components/parameters/accept"},{"schema":{"type":"string"},"in":"header","name":"Content-Type","description":"application/json"}],"x-supported-platforms":["national","international"]},"parameters":[{"schema":{"type":"string"},"name":"tax_id","description":"The tax id of the company","in":"path","required":true}]},"/companies/{tax_id}/subcontractors":{"get":{"summary":"Get subcontractors","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"in":"header","name":"Accept","description":"application/vnd.nalanda.api-v1.0+json"},{"schema":{"type":"string"},"in":"query","name":"page","description":"Number of the current page"},{"schema":{"type":"string"},"in":"query","name":"size","description":"Size for every page"},{"schema":{"type":"string"},"in":"query","name":"sort","description":"Sort by field"},{"$ref":"#/components/parameters/status"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"array","x-stoplight":{"id":"vh3wbwsx3gmxx"},"items":{"$ref":"#/components/schemas/Company"}},"page":{"$ref":"./Page.json"}}}}}},"401":{"description":"Unauthorized"},"403":{"$ref":"#/components/responses/403-Forbidden"},"404":{"$ref":"#/components/responses/404-Not-Found"},"406":{"$ref":"#/components/responses/406-Not-Acceptable"}},"operationId":"getSubcontractorsByTaxId","description":"<!-- BEGIN supported-platforms -->\n<!-- theme: none -->\n>#### Supported Platforms: NATIONAL / INTERNATIONAL\n<!-- END supported-platforms -->\n\nThe endpoint returns a list of companies that have a contractual relationship with the company associated to the tax id, i.e. it will return the companies that are directly associated through a work.","x-stoplight":{"id":"0vlcmi0mw66zv"},"x-supported-platforms":["national","international"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}}}}}},"parameters":[{"schema":{"type":"string"},"name":"tax_id","description":"The tax id of the company","in":"path","required":true}]},"/companies/{tax_id}/zones":{"parameters":[{"schema":{"type":"string"},"name":"tax_id","in":"path","required":true,"description":"Tax id of the company"}],"get":{"summary":"Find all zones for the company","tags":["zones"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"array","x-stoplight":{"id":"hiifh9liutc1u"},"items":{"$ref":"#/components/schemas/Zone"}},"page":{"$ref":"./Page.json"}}}}}},"401":{"$ref":"#/components/responses/401-Unauthorized"},"403":{"$ref":"#/components/responses/403-Forbidden"},"404":{"$ref":"#/components/responses/404-Not-Found"},"500":{"$ref":"#/components/responses/500-Internal-Server-Error"}},"operationId":"get-companies-tax_id-zones","x-stoplight":{"id":"ykbgqictxbtht"},"description":"<!-- BEGIN supported-platforms -->\n<!-- theme: none -->\n>#### Supported Platforms: NATIONAL / INTERNATIONAL\n<!-- END supported-platforms -->\n\nGet all the zones from the company by tax id","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/contentType"},{"$ref":"#/components/parameters/accept"},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/size"},{"$ref":"#/components/parameters/sort"}],"x-supported-platforms":["national","international"]},"post":{"summary":"Create zone for the company","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Zone"}}}},"400":{"$ref":"#/components/responses/400-Bad-Request"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"./Error.yaml"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"./Error.yaml"}}}},"406":{"description":"Not Acceptable","content":{"application/json":{"schema":{"$ref":"./Error.yaml"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"./Error.yaml"}}}}},"operationId":"post-companies-tax_id-zones","x-stoplight":{"id":"p1hedhijvk3hz"},"description":"<!-- BEGIN supported-platforms -->\n<!-- theme: none -->\n>#### Supported Platforms: NATIONAL / INTERNATIONAL\n<!-- END supported-platforms -->\n\nCreate a new zone for the company ","x-supported-platforms":["national","international"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/contentType"},{"$ref":"#/components/parameters/accept"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Zone"}}}},"tags":["zones"]}}},"tags":[{"name":"Logos","description":"Logos of the company"},{"name":"Zones","description":"Zone of the company"}]}