/api/entities
GET
Retrieve metadata about the entities that submit archives. These entities are also referred to by facts with the xbrl:Entity aspect, of which the values are called Entity IDs (EIDs). One entity might have several EIDs.
Parameters
| Name | Type | Description | Profile |
|---|---|---|---|
| profile-name | query | Specifies which profile to use, which will enable some parameters or modify hypercube queries accordingly. The default depends on the underlying repository | |
| format | query | Returns the results in the supplied format | |
| format-indent | query | Whether or not to indent JSON or XML output (default: no indent). | |
| token | query | The token that allows you to use this API. Gives you read (GET) and/or write (POST, DELETE, PATCH) credentials. | |
| entity-tag | query | The tag of an entity (such as an index), to retrieve entities, archives, sections, components or dice facts. | sec, japan |
| eid | query | The EIDs (scheme + local name) of a company, to retrieve entities, archives, sections, components or dice facts. | |
| cik | query | The CIK of a company, to retrieve entities, archives, sections, components or dice facts. | sec |
| edinetcode | query | The EDINET code of a company, to retrieve entities, archives, sections, components or dice facts. | japan |
| sic | query | The SIC (industry group) of a company, to retrieve entities, archives, sections, components or dice facts. | sec |
| ticker | query | The ticker of a company, to retrieve entities, archives, sections, components or dice facts. | sec, japan |
| entity-search | query | Includes in the results the entities whose name match this full-text query | japan |
| entity-search-offset | query | Includes in the results the entities whose name match the entity-search parameter skipping the first entity-search-offset results (default: 0) | japan |
| entity-search-limit | query | Includes in the results the entities whose name match the entity-search parameter limited to a maximum of entity-search-limit results (default: 100) | japan |
| language | query | Specifies in which language to perform the entity-search query (default: en-US) | japan |
| count | query | If true, only outputs statistics (default: false). | |
| top | query | Output only the first [top] results (default: no limit). | |
| skip | query | Skip the first [skip] results. |
Status codes
| Code | Description |
|---|---|
| 200 | Returns query listing |
| 401 | Unauthorized: the specified project token is invalid, expired, or has insufficient privileges |
| 500 | An internal error occurred during the processing of the request |
POST
Add or update entity. The entities are identified with Entity IDs (EIDs).
An entity must be specified as a JSON object that must be valid against a JSound schema. It can be either taken from the output of a GET request to the same endpoint (in which case it will be valid), or created manually.
For convenience, we offer a user-friendly summary of the fields involved. The JSound schema is available on request.
Body properties
| Field | Type | Presence | Content |
|---|---|---|---|
| EIDs | array of strings (at least one) | required | The EIDs for this entity. |
| Profiles | object | optional | Maps profile names to additional profile-specific information. The profile-specific information must have a Name field containing the profile name, that is, identical to its key. The other fields in the profile information is not restricted. |
Additionally, the following field is allowed for the purpose of feeding back the output of the entities endpoint as input:
- Archives (string)
Several entities can be created at the same time by posting a sequence of non-comma-separated JSON objects as above.
Parameters
| Name | Type | Description | Profile |
|---|---|---|---|
| format | query | Returns the results in the supplied format | |
| token | query | The token that allows you to use this API. Gives you read (GET) and/or write (POST, DELETE, PATCH) credentials. | |
| entity | body | The entity objects, which must be supplied in the body of the request, and which must satisfy the constraints described in the field table. |
Status codes
| Code | Description |
|---|---|
| 200 | Entities have been added. |
| 400 | One of the supplied entities is invalid. |
| 401 | Unauthorized: the specified project token is invalid, expired, or has insufficient privileges. |
| 403 | Access denied. |
| 409 | Duplicate entity in the input or entity already exists. |
| 500 | An internal error occurred during the processing of the request. |
DELETE
Deletes an entity.
Parameters
| Name | Type | Description | Profile |
|---|---|---|---|
| profile-name | query | Specifies which profile to use, which will enable some parameters or modify hypercube queries accordingly. The default depends on the underlying repository | |
| format | query | Returns the results in the supplied format | |
| format-indent | query | Whether or not to indent JSON or XML output (default: no indent). | |
| token | query | The token that allows you to use this API. Gives you read (GET) and/or write (POST, DELETE, PATCH) credentials. | |
| eid | query | The EID (scheme + local name) of a company. | |
| cik | query | The CIK of a company, to retrieve entities, archives, sections, components or dice facts. | sec |
| edinetcode | query | The EDINET code of a company, to retrieve entities, archives, sections, components or dice facts. | japan |
| ticker | query | The ticker of a company, to retrieve entities, archives, sections, components or dice facts. | sec, japan |
Status codes
| Code | Description |
|---|---|
| 204 | Entity has been deleted. |
| 400 | Cannot delete more than one entity at a time (safety mechanism). Or, Archives still exist for this entity. |
| 401 | Unauthorized: the specified project token is invalid, expired, or has insufficient privileges. |
| 403 | Access denied. |
| 404 | No such entity could be found. |
| 500 | An internal error occurred during the processing of the request. |
PATCH
Update one or more entities with partial information
Parameters
| Name | Type | Description | Profile |
|---|---|---|---|
| profile-name | query | Specifies which profile to use, which will enable some parameters or modify hypercube queries accordingly. The default depends on the underlying repository | |
| format | query | Returns the results in the supplied format | |
| format-indent | query | Whether or not to indent JSON or XML output (default: no indent). | |
| token | query | The token that allows you to use this API. Gives you read (GET) and/or write (POST, DELETE, PATCH) credentials. | |
| entity-tag | query | The tag of an entity (such as an index), to retrieve entities, archives, sections, components or dice facts. | sec, japan |
| eid | query | The EIDs (scheme + local name) of a company, to retrieve entities, archives, sections, components or dice facts. | |
| cik | query | The CIK of a company, to retrieve entities, archives, sections, components or dice facts. | sec |
| edinetcode | query | The EDINET code of a company, to retrieve entities, archives, sections, components or dice facts. | japan |
| sic | query | The SIC (industry group) of a company, to retrieve entities, archives, sections, components or dice facts. | sec |
| ticker | query | The ticker of a company, to retrieve entities, archives, sections, components or dice facts. | sec, japan |
| patch | body | The patch object, which will be merged into each entity (the entities must be valid after applying it). |
Updating the EID of an entity is not allowed. | |
Status codes
| Code | Description |
|---|---|
| 200 | Returns the patched entities |
| 400 | Bad request: a parameter is missing or invalid, or an entity is invalid after applying the patch, or an EID was updated |
| 401 | Unauthorized: the specified project token is invalid, expired, or has insufficient privileges |
| 403 | Access denied |
| 404 | No such entity could be found. |
| 500 | An internal error occurred during the processing of the request |