openapi: 3.0.1 info: title: North Data API description: Programmatic access to the North Data DB. termsOfService: https://www.northdata.de/_agb contact: name: North Data Support email: support@northdata.de version: 1.234.0 servers: - url: https://www.northdata.de/_api paths: /company/v1/company: get: description: Retrieve a company. parameters: - name: name in: query description: company name required: false style: form explode: true schema: type: string - name: address in: query description: company address (you only need to specify the city) required: false style: form explode: true schema: type: string - name: registerId in: query description: "the ID of under which the company is registered, for example\ \ HRB 12345" required: false style: form explode: true schema: type: string - name: registerCity in: query description: "the city of the court where the company is registered, for example\ \ Hamburg" required: false style: form explode: true schema: type: string - name: companyId in: query description: "internal company id (do not store this id in an external database,\ \ it may change over time)" required: false style: form explode: true schema: type: string - name: fuzzyMatch in: query description: true to find best match (similar name and nearby address) required: false style: form explode: true schema: type: boolean - name: registerKey in: query description: key that has been provided via the register uniqueKey field required: false style: form explode: true schema: type: string - name: history in: query description: true to include historical data required: false style: form explode: true schema: type: boolean - name: financials in: query description: true to include financial data required: false style: form explode: true schema: type: boolean - name: events in: query description: true to include event data required: false style: form explode: true schema: type: boolean - name: eventType in: query description: restrict which event types will be returned if events equals true required: false style: pipeDelimited explode: false schema: type: array - name: maxEvents in: query description: maximum number of events to return required: false style: form explode: true schema: type: integer format: int32 - name: relations in: query description: | true to include related company and person data. Note: For owners, only majority shareholders are included. For more owners, use the "owners" parameter instead. required: false style: form explode: true schema: type: boolean - name: owners in: query description: true to include all owners/shareholders (companies & persons) of the subject company required: false style: form explode: true schema: type: boolean - name: ownerships in: query description: true to include companies owned by the subject company. required: false style: form explode: true schema: type: boolean - name: representatives in: query description: "true to include legal representatives of the subject company\ \ (e.g., managing directors, board members)." required: false style: form explode: true schema: type: boolean - name: alwaysResolve in: query description: true to lookup current state of related company from database required: false style: form explode: true schema: type: boolean - name: sheets in: query description: "true to include company financial sheets (balance, earnings)" required: false style: form explode: true schema: type: boolean - name: extras in: query description: true to include extra company data provided by 3rd parties required: false style: form explode: true schema: type: boolean - name: output in: query description: response format required: false style: form explode: true schema: type: string default: json enum: - json - xml responses: "200": description: A successful response content: application/json: schema: $ref: "#/components/schemas/Company" application/xml: schema: $ref: "#/components/schemas/Company" /company/v1/publications: get: description: Retrieve the publications associated with a company. parameters: - name: name in: query description: company name required: false style: form explode: true schema: type: string - name: address in: query description: company address (you only need to specify the city) required: false style: form explode: true schema: type: string - name: registerId in: query description: "the ID of under which the company is registered, for example\ \ HRB 12345" required: false style: form explode: true schema: type: string - name: registerCity in: query description: "the city of the court where the company is registered, for example\ \ Hamburg" required: false style: form explode: true schema: type: string - name: companyId in: query description: "internal company id (do not store this id in an external database,\ \ it may change over time)" required: false style: form explode: true schema: type: string - name: fuzzyMatch in: query description: true to find best match (similar name and nearby address) required: false style: form explode: true schema: type: boolean - name: registerKey in: query description: key that has been provided via the register uniqueKey field required: false style: form explode: true schema: type: string - name: minTimestamp in: query description: minimum datetime publication was added to the database required: false style: form explode: true schema: type: string format: date-time - name: maxTimestamp in: query description: maximum datetime publication was added to the database required: false style: form explode: true schema: type: string format: date-time - name: minPublicationDate in: query description: minimum date publication was published on (by the source) required: false style: form explode: true schema: type: string format: date - name: maxPublicationDate in: query description: maximum date publication was published on (by the source) required: false style: form explode: true schema: type: string format: date - name: sources in: query description: DEPRECATED (will be removed at some point of time) required: false style: pipeDelimited explode: false schema: type: array - name: source in: query description: only publications with this source will be returned required: true style: form explode: true schema: type: string - name: content in: query description: whether to include publication text / html (may significantly slow down response) required: false style: form explode: true schema: type: boolean - name: attachments in: query description: "whether to include publication attachments (binary, such as\ \ images or PDF)" required: false style: form explode: true schema: type: boolean - name: censor in: query description: should be set when presenting the content on a public website required: false style: form explode: true schema: type: boolean - name: offset in: query description: offset of first item to return required: false style: form explode: true schema: type: integer format: int32 - name: limit in: query description: maximum number of items to return required: false style: form explode: true schema: type: integer format: int32 - name: output in: query description: response format required: false style: form explode: true schema: type: string default: json enum: - json - xml responses: "200": description: A successful response content: application/json: schema: $ref: "#/components/schemas/GenericResponse" application/xml: schema: $ref: "#/components/schemas/GenericResponse" /person/v1/person: get: description: Retrieve a person. parameters: - name: firstName in: query description: first name(s) of a person required: false style: form explode: true schema: type: string - name: lastName in: query description: last name of a person required: false style: form explode: true schema: type: string - name: address in: query description: person address (you only need to specify the city) required: false style: form explode: true schema: type: string - name: birthDate in: query description: birth date required: false style: form explode: true schema: type: string format: date - name: personId in: query description: "internal person id (do not store this id in an external database,\ \ it may change over time)" required: false style: form explode: true schema: type: string - name: history in: query description: true to include historical data required: false style: form explode: true schema: type: boolean - name: relations in: query description: | true to include related company and person data. Note: For owners, only majority shareholders are included. For more owners, use the "owners" parameter instead. required: false style: form explode: true schema: type: boolean - name: alwaysResolve in: query description: true to lookup current state of related company from database required: false style: form explode: true schema: type: boolean - name: output in: query description: response format required: false style: form explode: true schema: type: string default: json enum: - json - xml responses: "200": description: A successful response content: application/json: schema: $ref: "#/components/schemas/Person" application/xml: schema: $ref: "#/components/schemas/Person" /person/v1/publications: get: description: Retrieve the publications associated with a person. parameters: - name: firstName in: query description: first name(s) of a person required: false style: form explode: true schema: type: string - name: lastName in: query description: last name of a person required: false style: form explode: true schema: type: string - name: address in: query description: person address (you only need to specify the city) required: false style: form explode: true schema: type: string - name: birthDate in: query description: birth date required: false style: form explode: true schema: type: string format: date - name: personId in: query description: "internal person id (do not store this id in an external database,\ \ it may change over time)" required: false style: form explode: true schema: type: string - name: minTimestamp in: query description: minimum datetime publication was added to the database required: false style: form explode: true schema: type: string format: date-time - name: maxTimestamp in: query description: maximum datetime publication was added to the database required: false style: form explode: true schema: type: string format: date-time - name: minPublicationDate in: query description: minimum date publication was published on (by the source) required: false style: form explode: true schema: type: string format: date - name: maxPublicationDate in: query description: maximum date publication was published on (by the source) required: false style: form explode: true schema: type: string format: date - name: sources in: query description: DEPRECATED (will be removed at some point of time) required: false style: pipeDelimited explode: false schema: type: array - name: source in: query description: only publications with this source will be returned required: true style: form explode: true schema: type: string - name: content in: query description: whether to include publication text / html (may significantly slow down response) required: false style: form explode: true schema: type: boolean - name: attachments in: query description: "whether to include publication attachments (binary, such as\ \ images or PDF)" required: false style: form explode: true schema: type: boolean - name: censor in: query description: should be set when presenting the content on a public website required: false style: form explode: true schema: type: boolean - name: offset in: query description: offset of first item to return required: false style: form explode: true schema: type: integer format: int32 - name: limit in: query description: maximum number of items to return required: false style: form explode: true schema: type: integer format: int32 - name: output in: query description: response format required: false style: form explode: true schema: type: string default: json enum: - json - xml responses: "200": description: A successful response content: application/json: schema: $ref: "#/components/schemas/GenericResponse" application/xml: schema: $ref: "#/components/schemas/GenericResponse" /pub/v1/publications: get: description: "Retrieve publications. At most 10 publications are returned with\ \ each call. For more, repeat the call setting the pos parameter to the newPos\ \ attribute value of the response." parameters: - name: id in: query description: publication id to get a single publication required: false style: form explode: true schema: type: string - name: minDate in: query description: DEPRECATED - please use minTimestamp or minPublicationDate instead required: false style: form explode: true schema: type: string format: date - name: maxDate in: query description: DEPRECATED - please use maxTimestamp or maxPublicationDate instead required: false style: form explode: true schema: type: string format: date - name: minTimestamp in: query description: minimum datetime publication was added to the database required: false style: form explode: true schema: type: string format: date-time - name: maxTimestamp in: query description: maximum datetime publication was added to the database required: false style: form explode: true schema: type: string format: date-time - name: minPublicationDate in: query description: minimum date publication was published on (by the source) required: false style: form explode: true schema: type: string format: date - name: maxPublicationDate in: query description: maximum date publication was published on (by the source) required: false style: form explode: true schema: type: string format: date - name: sources in: query description: DEPRECATED (will be removed at some point of time) required: false style: pipeDelimited explode: false schema: type: array - name: source in: query description: only publications with this source will be returned required: true style: form explode: true schema: type: string - name: content in: query description: whether to include publication text / html (may significantly slow down response) required: false style: form explode: true schema: type: boolean - name: attachments in: query description: "whether to include publication attachments (binary, such as\ \ images or PDF)" required: false style: form explode: true schema: type: boolean - name: publisherHistory in: query description: true to include historical data for the publisher required: false style: form explode: true schema: type: boolean - name: publisherFinancials in: query description: true to include financial data for the publisher required: false style: form explode: true schema: type: boolean - name: publisherRelations in: query description: true to include related company and person data for the publisher required: false style: form explode: true schema: type: boolean - name: publisherEvents in: query description: true to include event data for the publisher required: false style: form explode: true schema: type: boolean - name: publisherExtras in: query description: true to include extra publisher data provided by 3rd parties required: false style: form explode: true schema: type: boolean - name: publisherSheets in: query description: "true to include publisher sheets (balance, earnings)" required: false style: form explode: true schema: type: boolean - name: pos in: query description: "if additional results shall be downloaded, set this to the value\ \ of the newPos attribute of the previous response" required: false style: form explode: true schema: type: string - name: censor in: query description: should be set when presenting the content on a public website required: false style: form explode: true schema: type: boolean - name: output in: query description: response format required: false style: form explode: true schema: type: string default: json enum: - json - xml responses: "200": description: A successful response content: application/json: schema: $ref: "#/components/schemas/GenericResponse" application/xml: schema: $ref: "#/components/schemas/GenericResponse" /search/v1/universal: get: description: "universal search: provides best company and person matches for\ \ given input query" parameters: - name: query in: query description: the query string required: true style: form explode: true schema: type: string - name: domain in: query description: "set to \"company\" for companies only, \"person\" for persons\ \ only, otherwise leave empty" required: false style: form explode: true schema: type: string - name: pos in: query description: "if additional results shall be downloaded, set this to the value\ \ of the nextPos attribute of the previous response" required: false style: form explode: true schema: type: string - name: censor in: query description: should be set when presenting the content on a public website required: false style: form explode: true schema: type: boolean - name: offset in: query description: offset of first item to return required: false style: form explode: true schema: type: integer format: int32 - name: limit in: query description: maximum number of items to return required: false style: form explode: true schema: type: integer format: int32 - name: output in: query description: response format required: false style: form explode: true schema: type: string default: json enum: - json - xml - name: countries in: query description: list of country ISO codes to restrict result set (empty to retrieve all countries). Valid values can be retrieved dynamically from the `/reference/v1/overview` endpoint. required: false style: form explode: true schema: type: string - name: status in: query description: "list of valid statuses (active, terminated, liquidation). Valid\ \ values can be retrieved dynamically from the `/reference/v1/overview`\ \ endpoint." required: false style: form explode: true schema: type: string - name: history in: query description: true to include historical data required: false style: form explode: true schema: type: boolean - name: financials in: query description: true to include financial data required: false style: form explode: true schema: type: boolean - name: events in: query description: true to include event data required: false style: form explode: true schema: type: boolean - name: eventType in: query description: restrict which event types will be returned if events equals true required: false style: pipeDelimited explode: false schema: type: array - name: maxEvents in: query description: maximum number of events to return required: false style: form explode: true schema: type: integer format: int32 - name: relations in: query description: | true to include related company and person data. Note: For owners, only majority shareholders are included. For more owners, use the "owners" parameter instead. required: false style: form explode: true schema: type: boolean - name: owners in: query description: true to include all owners/shareholders (companies & persons) of the subject company required: false style: form explode: true schema: type: boolean - name: ownerships in: query description: true to include companies owned by the subject company. required: false style: form explode: true schema: type: boolean - name: representatives in: query description: "true to include legal representatives of the subject company\ \ (e.g., managing directors, board members)." required: false style: form explode: true schema: type: boolean - name: alwaysResolve in: query description: true to lookup current state of related company from database required: false style: form explode: true schema: type: boolean - name: sheets in: query description: "true to include company financial sheets (balance, earnings)" required: false style: form explode: true schema: type: boolean - name: extras in: query description: true to include extra company data provided by 3rd parties required: false style: form explode: true schema: type: boolean responses: "200": description: A successful response content: application/json: schema: $ref: "#/components/schemas/SearchResults" application/xml: schema: $ref: "#/components/schemas/SearchResults" /search/v1/suggest: get: description: "auto complete: provides quick company and person suggestions for\ \ given input query" parameters: - name: query in: query description: the query string required: true style: form explode: true schema: type: string - name: domain in: query description: "\"company\" to match companies only, \"person\" to match persons\ \ only, empty to match all" required: false style: form explode: true schema: type: string - name: history in: query description: true to include former company names required: false style: form explode: true schema: type: boolean - name: censor in: query description: should be set when presenting the content on a public website required: false style: form explode: true schema: type: boolean - name: offset in: query description: offset of first item to return required: false style: form explode: true schema: type: integer format: int32 - name: limit in: query description: maximum number of items to return required: false style: form explode: true schema: type: integer format: int32 - name: output in: query description: response format required: false style: form explode: true schema: type: string default: json enum: - json - xml - name: countries in: query description: list of country ISO codes to restrict result set (empty to retrieve all countries). Valid values can be retrieved dynamically from the `/reference/v1/overview` endpoint. required: false style: form explode: true schema: type: string - name: status in: query description: "list of valid statuses (active, terminated, liquidation). Valid\ \ values can be retrieved dynamically from the `/reference/v1/overview`\ \ endpoint." required: false style: form explode: true schema: type: string responses: "200": description: A successful response content: application/json: schema: $ref: "#/components/schemas/SearchResults" application/xml: schema: $ref: "#/components/schemas/SearchResults" /search/v1/power: get: description: "power search: supports geo and financial criteria" parameters: - name: keywords in: query description: keywords to match in the company's subject required: false style: form explode: true schema: type: string - name: address in: query description: address or geo coordinates required: false style: form explode: true schema: type: string - name: maxDistanceKm in: query description: maximum distance from given address required: false style: form explode: true schema: type: number format: double - name: legalForm in: query description: list of legal forms and legal form families. Valid values can be retrieved dynamically from the `/reference/v1/overview` endpoint (see `legalForms` and `legalFormFamilies`). required: false style: form explode: true schema: type: string - name: segmentCodeStandard in: query description: name of the segment code standard to use. Valid values can be retrieved dynamically from the `/reference/v1/overview` endpoint. required: false style: form explode: true schema: type: string - name: segmentCodes in: query description: list of segment codes Valid values can be retrieved dynamically from the `/reference/v1/segmentCodes` endpoint. required: false style: form explode: true schema: type: string - name: indicatorId in: query description: list of indicator ids for performance filtering. Valid values can be retrieved dynamically from the `/reference/v1/overview` endpoint. required: false style: pipeDelimited explode: false schema: type: array items: type: string - name: lowerBound in: query description: list of lower bounds for performance filterings (see user guide) required: false style: pipeDelimited explode: false schema: type: array items: type: number format: double - name: upperBound in: query description: list of upper bounds for performance filterings (see user guide) required: false style: pipeDelimited explode: false schema: type: array items: type: number format: double - name: lowerBoundUnit in: query description: list of lower bound units. Only required for currencies different from EUR required: false style: pipeDelimited explode: false schema: type: array items: type: string - name: upperBoundUnit in: query description: list of upper bound units. Only required for currencies different from EUR required: false style: pipeDelimited explode: false schema: type: array items: type: string - name: events in: query description: true to include event data required: false style: form explode: true schema: type: boolean - name: eventType in: query description: list of event types for event filtering. Valid values can be retrieved dynamically from the `/reference/v1/overview` endpoint. required: false style: pipeDelimited explode: false schema: type: array items: type: string - name: minDate in: query description: list of minimum dates for event filterings (see user guide) required: false style: pipeDelimited explode: false schema: type: array items: type: string format: date - name: maxDate in: query description: list of maximum dates for event filterings (see user guide) required: false style: pipeDelimited explode: false schema: type: array items: type: string format: date - name: countries in: query description: list of country ISO codes to restrict result set (empty to retrieve all countries). Valid values can be retrieved dynamically from the `/reference/v1/overview` endpoint. required: false style: form explode: true schema: type: string - name: status in: query description: "list of valid statuses (active, terminated, liquidation). Valid\ \ values can be retrieved dynamically from the `/reference/v1/overview`\ \ endpoint." required: false style: form explode: true schema: type: string - name: history in: query description: true to include historical data required: false style: form explode: true schema: type: boolean - name: financials in: query description: true to include financial data required: false style: form explode: true schema: type: boolean - name: maxEvents in: query description: maximum number of events to return required: false style: form explode: true schema: type: integer format: int32 - name: relations in: query description: | true to include related company and person data. Note: For owners, only majority shareholders are included. For more owners, use the "owners" parameter instead. required: false style: form explode: true schema: type: boolean - name: owners in: query description: true to include all owners/shareholders (companies & persons) of the subject company required: false style: form explode: true schema: type: boolean - name: ownerships in: query description: true to include companies owned by the subject company. required: false style: form explode: true schema: type: boolean - name: representatives in: query description: "true to include legal representatives of the subject company\ \ (e.g., managing directors, board members)." required: false style: form explode: true schema: type: boolean - name: alwaysResolve in: query description: true to lookup current state of related company from database required: false style: form explode: true schema: type: boolean - name: sheets in: query description: "true to include company financial sheets (balance, earnings)" required: false style: form explode: true schema: type: boolean - name: extras in: query description: true to include extra company data provided by 3rd parties required: false style: form explode: true schema: type: boolean - name: pos in: query description: "if additional results shall be downloaded, set this to the value\ \ of the nextPos attribute of the previous response" required: false style: form explode: true schema: type: string - name: censor in: query description: should be set when presenting the content on a public website required: false style: form explode: true schema: type: boolean - name: limit in: query description: maximum number of items to return required: false style: form explode: true schema: type: integer format: int32 - name: output in: query description: response format required: false style: form explode: true schema: type: string default: json enum: - json - xml responses: "200": description: A successful response content: application/json: schema: $ref: "#/components/schemas/SearchResults" application/xml: schema: $ref: "#/components/schemas/SearchResults" /reference/v1/overview: get: description: "Returns meta information about the API, such as supported parameter\ \ values for power search." responses: "200": description: A successful response content: application/json: schema: $ref: "#/components/schemas/OverviewResponse" application/xml: schema: $ref: "#/components/schemas/OverviewResponse" /reference/v1/segmentCodes: get: description: Returns the list of segment codes for the requested standard. The `standard` parameter must be one of the segment code standards available in the `/reference/v1/overview` endpoint (`segmentCodeStandards`). parameters: - name: standard in: query description: "Segment code standard name, as returned in the `segmentCodeStandards`\ \ property of `/reference/v1/overview`." required: true style: form explode: true schema: type: string responses: "200": description: List of available segment codes for the requested standard. content: application/json: schema: type: array items: type: string description: Segment code example: "62.01" application/xml: schema: type: array items: type: string description: Segment code example: "62.01" "400": description: Invalid or unsupported segment code standard content: {} /billing/v1/requests: get: description: number of unique requests parameters: - name: year in: query description: year of the billing period (>= 2024) required: false style: form explode: true schema: minimum: 2024 type: integer format: int32 - name: month in: query description: month of the billing period between 1 (January) and 12 ( December) required: false style: form explode: true schema: maximum: 12 minimum: 1 type: integer format: int32 - name: output in: query description: response format required: false style: form explode: true schema: type: string default: json enum: - json - xml responses: "200": description: A successful response content: application/json: schema: $ref: "#/components/schemas/Billing" application/xml: schema: $ref: "#/components/schemas/Billing" components: schemas: Company: title: Company required: - address - id - name type: object properties: id: type: string description: "internal company id (do not store this id in an external database,\ \ it may change over time)" name: $ref: "#/components/schemas/CompanyName" rawName: type: string description: May provide the raw name found in register sources before applying normalizations and spelling fixes address: $ref: "#/components/schemas/Address" register: $ref: "#/components/schemas/Register" lei: type: string description: International Legal Entity Identifier (LEI) euId: type: string description: European Unique Identifier (EUID) elfCode: type: string description: current entity legal form code according to ISO 20275 subject: type: string description: "subject according to register filing (also called corporate\ \ object, purpose, Unternehmensgegenstand), possibly translated" originalSubject: type: string description: "subject according to register filing (also called corporate\ \ object, purpose, Unternehmensgegenstand), in the original language" originalSubjectLang: type: string description: original language of the subject proxyPolicy: type: string description: "rules for representation by legal representatives (e.g., signatory\ \ authority)" segmentCodes: type: object additionalProperties: type: array items: type: string description: "each property (naics, isic, nace, wz, uksic) contains a list\ \ of segment codes in respective standard classification" northDataUrl: type: string description: North data web page for this company terminated: type: boolean description: company has been terminated status: type: string description: "current status of the company, where liquidation is the intermediate\ \ state before the final removal from the register (=terminated)" enum: - active - liquidation - terminated history: $ref: "#/components/schemas/CompanyHistory" capital: $ref: "#/components/schemas/Financials" financials: $ref: "#/components/schemas/Financials" mktgTechIndicators: $ref: "#/components/schemas/Financials" events: $ref: "#/components/schemas/Events" extras: type: array description: extra data provided by 3rd parties items: $ref: "#/components/schemas/Extras" sheets: type: array description: company's financial sheets (such as balance and earnings sheets) items: $ref: "#/components/schemas/Sheet" relatedCompanies: $ref: "#/components/schemas/Relations" relatedPersons: $ref: "#/components/schemas/Relations" filings: type: array description: external source-specific IDs items: $ref: "#/components/schemas/Filing" blocked: type: boolean description: company data should not be publicly on the Internet because of a request for privacy protection lastUpdateTime: type: string description: last time this company was updated format: date-time description: All data for a particular company CompanyName: required: - name type: object properties: name: type: string description: name of a company legalForm: type: string description: "legal form (for example: A/S, AG, AG & Co. KG, AöR, Co. KG,\ \ d.o.o., e. K., e. V., eG, EWIV, gAG, GbR, gGmbH, GmbH, GmbH & Co. KG,\ \ gSE, gUG, Inh., InvAG, KG, KGaA, KGaA & Co. KG, Ltd., Ltd. & Co. KG,\ \ OHG, PartGG, plc, REITG, S.L., SCE, SCE, SCE mbH, SE, SE & Co. KG, Stiftung\ \ & Co. KG, UG, UG & Co. KG, VVaG)" Register: required: - id type: object properties: country: type: string description: register country (two-letter ISO code) city: type: string description: city of the register court (e.g. Hamburg). Empty for most countries. id: type: string description: ID of the register filing (e.g. HRB 9999) uniqueKey: type: string description: unique numerical key for repeatably unique identification of the register entry description: "register entry information (e.g., Amtsgericht Hamburg HRB 9999)" Filing: required: - id type: object properties: type: type: string description: filing type name: type: string description: complete string source: $ref: "#/components/schemas/PublicationSource" city: type: string description: city (only for German insolvency filings) id: type: string description: "external ID (e.g., 36w IN 3284/16 for insolvency filings)" description: Filings are external IDs that are used by an external source (for example the insolvency filing ID for the Ins source) Address: required: - city - country type: object properties: street: type: string description: street and house number extra: type: string description: extra address information (such as c/o) postalCode: type: string description: postal code city: type: string description: city state: type: string description: state country: type: string description: two-letter ISO country code lat: type: number description: "geo coordinates, latitude part" format: double lng: type: number description: "geo coordinates, longitude part" format: double formattedValue: type: string description: the whole address in one human readable string CompanyNameHistoryItem: required: - name type: object properties: name: $ref: "#/components/schemas/CompanyName" date: type: string description: since when the referred company name is (known to be) in use format: date AddressHistoryItem: required: - address type: object properties: address: $ref: "#/components/schemas/Address" date: type: string description: since when the referred address is (known to be) in use format: date RegisterHistoryItem: required: - register type: object properties: register: $ref: "#/components/schemas/Register" date: type: string description: since when this registry entry is valid format: date CompanyHistory: type: object properties: names: type: array description: name history of a company items: $ref: "#/components/schemas/CompanyNameHistoryItem" addresses: type: array description: adress history of a company items: $ref: "#/components/schemas/AddressHistoryItem" registers: type: array description: register entry history of a company items: $ref: "#/components/schemas/RegisterHistoryItem" financials: type: array description: historical financial data items: $ref: "#/components/schemas/Financials" mktgTechIndicators: type: array description: historical financial data items: $ref: "#/components/schemas/Financials" Events: required: - items type: object properties: items: type: array description: the list of events items: $ref: "#/components/schemas/Event" description: list of events Event: type: object properties: type: type: string description: one of ... date: type: string description: when it happened format: date description: type: string description: human-readable description of what happend description: event Financials: required: - consolidated - date - formattedDate - items type: object properties: date: type: string description: reference date format: date formattedDate: type: string description: date formatted as a string (depending on the language settings) consolidated: type: boolean description: true if the financial data refer to a consolidated balance (Konzernabschluss) source: $ref: "#/components/schemas/FinancialsSource" items: type: array description: "list of financial numbers (maybe empty. If empty, see note\ \ for the reason)" items: $ref: "#/components/schemas/Financial" note: $ref: "#/components/schemas/FinancialsNote" description: financial data Financial: required: - formattedValue - id - name - value type: object properties: id: type: string description: "type of number (for example, revenue). Please see the [indicator\ \ reference](https://www.northdata.com/_coverage#indicators) for a complete\ \ list" name: type: string description: "name in current language (for example, Umsatz in German or\ \ Revenue in English)" value: type: number description: actual value format: double unit: type: string description: "unit or currency (EUR, % or empty)" estimate: type: boolean description: true if the value is not exact (because it relies on an estimate or an unsafe determination method) note: type: string description: optional note or comment with respect to the calculation of the financial formattedValue: type: string description: value formatted as a string (depending on the language settings) description: single financial number FinancialsSource: required: - publicationDate - publicationTitle type: object properties: publicationId: type: string description: internal publication ID publicationTitle: type: string description: publication title such as "Jahresabschluss 2015" publicationDate: type: string description: date the publication was published format: date auditorName: type: string description: name of auditing company snippets: type: array description: excerpts from the original publication containing the financial data items: $ref: "#/components/schemas/SourceSnippet" description: source of financial data FinancialsNote: required: - html - text type: object properties: text: type: string description: explanation as plain text html: type: string description: explanation as html description: additional explanation of financials (or of their absence) SourceSnippet: required: - content - title type: object properties: title: type: string description: title content: type: string description: text contentType: type: string description: "content format, usually \"text/html\"" description: excerpts from an original publication Extras: type: object properties: sourceName: type: string description: name of the source sourceUrl: type: string description: url of the source items: type: array description: extra data items in this set items: $ref: "#/components/schemas/Extra" description: "set of additional data, typically provided by 3rd parties." Extra: required: - formattedHtmlValue - id - name - value type: object properties: id: type: string description: "common ids are: email, url, phone, fax, vatId, wz" name: type: string description: "describing name (for example, \"Email\" with English language\ \ settings, \"E-Mail\" with German language settigns)" value: type: string description: actual value formattedHtmlValue: type: string description: value formatted as an HTML string description: "extra data item, typically provided by a 3rd party." Publication: required: - id - source - title type: object properties: id: type: string description: interne ID date: type: string description: publishing date format: date effectiveDate: type: string description: "date when published changes became effective (e.g., appointment\ \ of new director)" format: date creationTime: type: string description: database creation time (which is right after the initial publication download) format: date-time source: $ref: "#/components/schemas/PublicationSource" sourceName: type: string description: full name of source category: type: string description: category under which publication was filed in the original source originalLanguage: type: string description: ISO language code language: type: string description: "ISO language code. This is different from the original language,\ \ for translations only." title: type: string description: title of publication northDataUrl: type: string description: North data web page for this publication text: type: string description: raw text of the publication html: type: string description: text of publication in HTML format publisher: $ref: "#/components/schemas/Company" structure: $ref: "#/components/schemas/PublicationStructure" mentionedCompanies: $ref: "#/components/schemas/Relations" mentionedPersons: $ref: "#/components/schemas/Relations" filings: type: array description: external filing IDs (e.g. insolvency filing IDs) items: $ref: "#/components/schemas/Filing" attachments: type: array description: additional binary content such as images or PDF items: $ref: "#/components/schemas/Attachment" blocked: type: boolean description: publication data should not be publicly on the Internet because of a request for privacy protection internal: type: object properties: {} description: additional data used for internal purposes Topic: required: - name - type type: object properties: name: type: string description: textual description value: type: string description: "accompanying value (e.g., €100.000,-)" type: type: string description: "internal identificator for the topic (for possible values,\ \ see Appendix E of the user's guide)" description: topic of a publication PublicationStructure: type: object properties: topics: type: array description: topics of the publication items: $ref: "#/components/schemas/Topic" description: result of the structural analysis of a publication PublicationSource: type: string description: "Source identifier, for a complete list see [Source reference](https://www.northdata.com/_coverage#sources)\ \ \n" EventType: type: string description: "event type (for possible values, see Appendix G of the user's\ \ guide)" Relation: required: - roles type: object properties: company: $ref: "#/components/schemas/Company" person: $ref: "#/components/schemas/Person" description: type: string description: human readable short summary roles: type: array description: description of the type of the relation items: $ref: "#/components/schemas/Role" description: relation of a company or person to another company or person Relations: required: - items type: object properties: items: type: array items: $ref: "#/components/schemas/Relation" description: list of related companies / persons Role: required: - group - name - type type: object properties: date: type: string description: date format: date name: type: string description: description (depending on the current language settings) detail: type: string description: depending on role and country demotion: type: boolean description: true if the relation ends at the given date announce: type: boolean description: true if the relation might be preliminary type: type: string description: "internal identifier (for possible values, see Appendix F of\ \ the API User Guide)" group: type: string description: internal group identifier enum: - Succession - Control - Merger - Personal - Other - Interest dir: type: string description: Direction. The exact interpretation depends of the value of the field "group". See the API User Guide for details. enum: - None - Source - Target - Bi sharesPercent: type: number description: shares in percent format: double sharesNominal: $ref: "#/components/schemas/Role_sharesNominal" description: description of the type of a relation PersonName: required: - lastName type: object properties: firstName: type: string description: first name(s) lastName: type: string description: last name title: type: string description: title Person: required: - id - name type: object properties: id: type: string description: "internal person id (do not store this id in an external database,\ \ it may change over time)" name: $ref: "#/components/schemas/PersonName" address: $ref: "#/components/schemas/Address" birthDate: type: string description: Birth date format: date birthYear: type: integer description: "Sometimes only the birth years is known, but not the exact\ \ date" format: int32 birthMonth: type: integer description: "Sometimes only birth year and month are known, but not the\ \ exact date" format: int32 deceased: type: boolean description: person is known to be dead northDataUrl: type: string description: North data web page for this person relatedCompanies: $ref: "#/components/schemas/Relations" filings: type: array description: external source-specific IDs items: $ref: "#/components/schemas/Filing" blocked: type: boolean description: person data should not be publicly on the Internet because of a request for privacy protection lastUpdateTime: type: string description: last time this person was updated format: date-time GenericResponse: type: object properties: newPos: type: string publications: type: array items: $ref: "#/components/schemas/Publication" SearchResults: type: object properties: results: type: array description: list of results items: $ref: "#/components/schemas/SearchResult" censored: type: boolean description: true if results have been omitted because of censoring offset: type: integer description: offset of result array in all results format: int32 nextOffset: type: integer description: offset to retrieve next batch of results format: int32 nextPos: type: string description: position to retrieve next batch of results total: type: integer description: "total number of results (usually, this number is not available,\ \ unfortunately)" format: int32 description: search results SearchResult: type: object properties: company: $ref: "#/components/schemas/Company" person: $ref: "#/components/schemas/Person" publication: $ref: "#/components/schemas/Publication" matchedName: type: string description: the matched name (useful if a company has been renamed) description: "company, person or publication that is result of a search" Money: required: - amount - currency - formattedValue type: object properties: currency: type: string description: currency (three-letter code) amount: type: number description: amount as a number format: double formattedValue: type: string description: amount and currency formatted as a human-readable string description: amount and currency Product: required: - id - name - price type: object properties: id: type: string description: string to identify a product when ordering for download name: type: string description: name of the product date: type: string description: publishing date format: date price: $ref: "#/components/schemas/Money" description: a publication that can be bought and downloaded Order: type: object properties: id: type: string description: string to identify the order items: type: array items: $ref: "#/components/schemas/OrderItem" description: result of an order OrderItem: required: - status type: object properties: product: $ref: "#/components/schemas/Product" status: type: string description: whether the publication is ready for download enum: - waiting - ready - unavailable url: type: string description: url to download from (when the status is 'ready') contentType: type: string description: mime type description: information whether and where a product maybe downloaded Sheet: required: - columnHeaders - consolidated - rows - type type: object properties: columnHeaders: type: array description: list of column headers items: $ref: "#/components/schemas/SheetColumnHeader" rows: type: array description: list of rows items: $ref: "#/components/schemas/SheetRow" type: type: string description: the kind of financial data reported in this sheet enum: - balance - earnings - cashflow consolidated: type: boolean description: true if the financial is consolidated (including dependent companies) or not (excluding) reporting: type: string description: the reporting standard used enum: - HGB - IFRS - GAAP unit: type: string description: "unit or currency (EUR, % or empty)" description: "represents balance sheets, profit and loss statements, and similar\ \ structures" SheetColumnHeader: required: - date type: object properties: date: type: string description: the date of entries in this column format: date source: $ref: "#/components/schemas/FinancialsSource" description: column header of a sheet SheetRow: required: - cells - name type: object properties: name: type: string description: name of row level: type: integer description: "if the sheet is structured as a tree, indicates the depth\ \ of the nesting of this row." format: int32 cells: type: array description: list of cells items: $ref: "#/components/schemas/SheetCell" description: row of a sheet SheetCell: type: object properties: value: type: number description: numeric value format: double description: cell of a sheet Attachment: required: - contentType - name - url type: object properties: name: type: string description: name of attachment url: type: string description: url to download from (link will be valid for 3 days) contentType: type: string description: mime type description: binary content related to a publication OverviewResponse: type: object properties: countries: type: object description: List of supported countries. allOf: - $ref: "#/components/schemas/ApplicableCountries" eventTypes: type: array description: List of available events for power search. items: $ref: "#/components/schemas/EventTypeOverview" legalFormFamilies: type: array description: List of available legal form families for power search. items: type: string legalForms: type: array description: List of available legal forms for power search. items: $ref: "#/components/schemas/LegalFormOverview" legalStatuses: type: array description: List of possible states in the lifecycle of a company. items: type: string performanceIndicators: type: array description: List of available performance indicators for power search. items: $ref: "#/components/schemas/PerformanceIndicatorOverview" registers: type: array items: $ref: "#/components/schemas/RegisterOverview" roleTypes: type: array description: List of available role types. items: type: string segmentCodeStandards: type: array description: List of supported segment code standards available for power search. items: type: string sources: type: array items: type: string topicTypes: type: array items: type: string EventTypeOverview: type: object properties: id: type: string description: Event type identifier (matches values accepted by `EventType` input) countries: type: array description: List of two-letter ISO country codes where this event type is supported items: type: string description: An event type and the countries where it is available. LegalFormOverview: type: object properties: id: type: string countries: $ref: "#/components/schemas/ApplicableCountries" description: A legal form and the countries where it is available. PerformanceIndicatorOverview: type: object properties: id: type: string countries: $ref: "#/components/schemas/ApplicableCountries" description: A performance indicator and the countries where it is available. RegisterOverview: type: object properties: country: type: string description: Register country (two-letter ISO code) name: type: string description: Name of the register authority (localised depending on the language settings when possible) sample: type: string description: A representative example of how a register ID would look like description: A country's register and an example entry. ApplicableCountries: type: array description: List of applicable countries (two-letter ISO codes). items: type: string Billing: type: object properties: periodStart: type: string description: begin of the billing period format: date periodEnd: type: string description: end of the billing period format: date numberOfRequests: type: integer description: number of unique requests format: int32 description: number of requests in billing period Role_sharesNominal: required: - unit - value type: object properties: value: type: number description: actual value format: double unit: type: string description: "unit or currency (EUR, % or empty)" description: nominal shares parameters: companyName: name: name in: query description: company name required: false style: form explode: true schema: type: string companyAddress: name: address in: query description: company address (you only need to specify the city) required: false style: form explode: true schema: type: string companyRegisterCity: name: registerCity in: query description: "the city of the court where the company is registered, for example\ \ Hamburg" required: false style: form explode: true schema: type: string companyRegisterId: name: registerId in: query description: "the ID of under which the company is registered, for example HRB\ \ 12345" required: false style: form explode: true schema: type: string companyId: name: companyId in: query description: "internal company id (do not store this id in an external database,\ \ it may change over time)" required: false style: form explode: true schema: type: string fuzzyMatch: name: fuzzyMatch in: query description: true to find best match (similar name and nearby address) required: false style: form explode: true schema: type: boolean registerKey: name: registerKey in: query description: key that has been provided via the register uniqueKey field required: false style: form explode: true schema: type: string personFirstName: name: firstName in: query description: first name(s) of a person required: false style: form explode: true schema: type: string personLastName: name: lastName in: query description: last name of a person required: false style: form explode: true schema: type: string personAddress: name: address in: query description: person address (you only need to specify the city) required: false style: form explode: true schema: type: string birthDate: name: birthDate in: query description: birth date required: false style: form explode: true schema: type: string format: date personId: name: personId in: query description: "internal person id (do not store this id in an external database,\ \ it may change over time)" required: false style: form explode: true schema: type: string minPublicationDate: name: minPublicationDate in: query description: minimum date publication was published on (by the source) required: false style: form explode: true schema: type: string format: date maxPublicationDate: name: maxPublicationDate in: query description: maximum date publication was published on (by the source) required: false style: form explode: true schema: type: string format: date minTimestamp: name: minTimestamp in: query description: minimum datetime publication was added to the database required: false style: form explode: true schema: type: string format: date-time maxTimestamp: name: maxTimestamp in: query description: maximum datetime publication was added to the database required: false style: form explode: true schema: type: string format: date-time sources: name: sources in: query description: DEPRECATED (will be removed at some point of time) required: false style: pipeDelimited explode: false schema: type: array source: name: source in: query description: only publications with this source will be returned required: true style: form explode: true schema: type: string content: name: content in: query description: whether to include publication text / html (may significantly slow down response) required: false style: form explode: true schema: type: boolean attachments: name: attachments in: query description: "whether to include publication attachments (binary, such as images\ \ or PDF)" required: false style: form explode: true schema: type: boolean censor: name: censor in: query description: should be set when presenting the content on a public website required: false style: form explode: true schema: type: boolean offset: name: offset in: query description: offset of first item to return required: false style: form explode: true schema: type: integer format: int32 limit: name: limit in: query description: maximum number of items to return required: false style: form explode: true schema: type: integer format: int32 pos: name: pos in: query description: "if additional results shall be downloaded, set this to the value\ \ of the nextPos attribute of the previous response" required: false style: form explode: true schema: type: string output: name: output in: query description: response format required: false style: form explode: true schema: type: string default: json enum: - json - xml history: name: history in: query description: true to include historical data required: false style: form explode: true schema: type: boolean financials: name: financials in: query description: true to include financial data required: false style: form explode: true schema: type: boolean mktgtech: name: mktgtech in: query description: true to include marketing & technology indicators required: false style: form explode: true schema: type: boolean events: name: events in: query description: true to include event data required: false style: form explode: true schema: type: boolean eventType: name: eventType in: query description: restrict which event types will be returned if events equals true required: false style: pipeDelimited explode: false schema: type: array maxEvents: name: maxEvents in: query description: maximum number of events to return required: false style: form explode: true schema: type: integer format: int32 relations: name: relations in: query description: | true to include related company and person data. Note: For owners, only majority shareholders are included. For more owners, use the "owners" parameter instead. required: false style: form explode: true schema: type: boolean owners: name: owners in: query description: true to include all owners/shareholders (companies & persons) of the subject company required: false style: form explode: true schema: type: boolean ownerships: name: ownerships in: query description: true to include companies owned by the subject company. required: false style: form explode: true schema: type: boolean representatives: name: representatives in: query description: "true to include legal representatives of the subject company (e.g.,\ \ managing directors, board members)." required: false style: form explode: true schema: type: boolean countries: name: countries in: query description: list of country ISO codes to restrict result set (empty to retrieve all countries). Valid values can be retrieved dynamically from the `/reference/v1/overview` endpoint. required: false style: form explode: true schema: type: string status: name: status in: query description: "list of valid statuses (active, terminated, liquidation). Valid\ \ values can be retrieved dynamically from the `/reference/v1/overview` endpoint." required: false style: form explode: true schema: type: string sheets: name: sheets in: query description: "true to include company financial sheets (balance, earnings)" required: false style: form explode: true schema: type: boolean extras: name: extras in: query description: true to include extra company data provided by 3rd parties required: false style: form explode: true schema: type: boolean alwaysResolve: name: alwaysResolve in: query description: true to lookup current state of related company from database required: false style: form explode: true schema: type: boolean billingYear: name: year in: query description: year of the billing period (>= 2024) required: false style: form explode: true schema: minimum: 2024 type: integer format: int32 billingMonth: name: month in: query description: month of the billing period between 1 (January) and 12 ( December) required: false style: form explode: true schema: maximum: 12 minimum: 1 type: integer format: int32 x-original-swagger-version: "2.0"