Hi Developer Community,
I'm working on a project to download English-language annual reports for German listed companies (from 2018-2024) using the Refinitiv Data Platform APIs, specifically the Search API (/search/beta1/
) and the Filings GraphQL API (/data-store/v1/graphql
). I've made some progress but have hit a couple of key roadblocks where your expertise would be invaluable.
My Current Approach & Successes:
- Authentication: Successfully obtaining an access token using password grant with the
trapi
scope. - Identifying German Organizations (Search API -
/search/beta1/
):- Using
View: "Organisations"
. - Filtering with
RCSCountryHeadquartersLeaf eq 'Germany' and OrganisationStatus xeq 'Listed'
. - Using
Select: "_debugall"
to inspect the full response. - Successfully extracting the Organization PermID from
raw_source.OAPermID
(e.g., for Bertelsmann SE & Co KgaA, OAPermID: 5037662836
).
Current Challenges & Questions:
1. Regarding the Search API (/search/beta1/
with View: "Organisations"
):
- Is
raw_source.OAPermID
the definitive and most reliable field for obtaining the Organization PermID when using View: "Organisations"
? - Is there a more direct way to request the Organization PermID in the
Select
clause for this view, rather than relying on _debugall
(which returns a very large payload)? We've found that directly selecting PermID
at the top level of the hit does not yield the Organization PermID in this view.
2. Regarding the Filings GraphQL API (/data-store/v1/graphql
):
- Primary Issue: Null DocumentSummary
- Fields: When querying for filings using a valid OrganizationId (e.g., 5037662836 for Bertelsmann) and a date range, even if we remove all FormType or HighLevelCategory filters to get all document types, the fields within DocumentSummary (specifically DocumentTitle, FilingDate, FormType, DocumentType, FeedName, HighLevelCategory) are consistently returning null for all retrieved filings. Is this an expected behavior for certain filings/companies?
- Could this be an entitlement issue where the DocId is accessible but the detailed metadata within DocumentSummary is restricted for my App Key/user?
- Or is there a different way to select these fields if they are nested differently than expected?
- Identifying English Annual Reports (Server-Side):
- What are the specific FormType codes that should be used in the GraphQL filter to reliably identify English-language Annual Reports for German/European companies? (e.g., the equivalent of "10-K" for US filings). We have tried "AR" and "GBR" without success (returned 0 filings for Bertelsmann, suggesting these are not the right codes or are not used for this company).
- Is there a recommended DocumentType or HighLevelCategory value that specifically targets English annual reports for this region? The "Filings Service Developer Guide" (Nov 2020 version) has examples for US filings but lacks a comprehensive list for other regions/report types.
- Language Filtering:
- Is there a way to directly filter filings by language (e.g., for "English") within the GraphQL query?
Goal:My ultimate goal is to reliably identify and download the PDF documents for English-language annual reports for a list of German companies between 2018-2024. Or to download the letter to shareholders sections of those reports in eg. a csv file.
Any guidance, examples, or pointers to more detailed documentation on the DocumentSummary
fields for the Filings API, or correct FormType
codes for European annual reports, would be immensely appreciated!
Thank you for your help!