Below you'll find additional context for our API Reference here.

Prefer learning more with your Microsoft Copilot or other AI assistant? No problem! ▶️ Here you'll find a quick video demo with examples of how this can be done for most of our automation solutions, and more here. 

🔗 Title & Link: Athennian API Reference

Introduction

Welcome

This public Reference webpage is Athennian's most official technical documentation defining the individual parts of our API (application protocol interface). This meaning it's also readable by most AI research assistants, and generally the best place to inspect our schema. It's contents are published primarily by our engineering department. For security reasons, our API is currently not available for direct introspection, downloading, or code-hinting. For supplementary documentation, please see visit our Help Center for AI assistance, ERD / Entity Relationship Diagram, etc.

In searching this document, calculating distribution, and understanding our current data model configuration, you may find it helpful to type Control / Command + F and search by various document syntax. For example, currently "- [Affiliation" shows that the Affiliation collection data can be found in 4 places including as a sub-collection in 3 places (Entity, Person, Registration), etc.

Features

Our API does not currently support all the data or functionality available within the Athennian app GUI (graphical user interface), and may even vary in how the same end result is achieved. However, the most common integration use case requirements are generally supported. For example, in the app GUI you can get some Shareholding data via Affiliations, etc. However, via the API Shareholdings and Affiliations are accessible completely separately.

Our API includes various read and write operations here called queries and mutations (create, update, delete, and combine). Some examples include Entities, People, Affiliations, createEntity, updateEntity, combineEntity, etc. Those operations use a mix of smaller parts called Types including primary collections and nested sub-collections (ie Entity, Person, Affiliation...), data formats (ie ID...), Field Names, etc. Descriptions are generally provided which may or may not provide additional API context, app GUI references, etc.

Some data can be accessed without any filter or Input Argument Options, but some cannot (ie, entityQueryOptions vs AddressesOptions). An exclamation mark (!) will generally mean either: 1) input required (ie recordIds - [ID!]!) or, 2) a non-nullable data field value (ie. id - UUID! Id of the address). However, some Responses will be paginated so it may be considered best practice to always use Limit, Skip, etc when available (ie. Entities). Generally we'll always require various kinds of response limits through default or otherwise required Options (like pagination, identifiers, etc). For security reasons, we may choose to document other limits as well in the future

Since identifiers often vital, please note that we have a variety of combinations of identifier name and type combinations. For example depending on your use case, there are 4+ names (id, Id, ID, and UUID), and 3+ types (ID, UUID, and String).

Please note that both queries and mutations have Query, Variable, Response, and Example code examples. And though we do have API validation, error prompts, etc, we currently do not document those directly here so you may encounter those separately during your application. Further more, our response code and validation can vary a bit more than just pass or fail. For example, a 200 code response could return all data expected or partial for various reasons. As mentioned above, various limits may apply. Also, part of the data may be returned, but a error message for part of the data may also be returned. This is important to account for during development.

Therefore, API macro use cases or micro Operations often require multiple Requests or calls for various reasons alluded to above.

Product

Our technology is primary GraphQL with some REST parts. For example, document file metadata is accessed via GraphQL, while document files themselves are accessed via REST. And therefore our API may not RESTful.

GraphQL may have various pros and cons depending on your use case, but generally this technology is newer and more customizable than more traditional options like RESTful.

And though our technology is very accessible it may not be considered a fully open by all such as OAI / OpenAPI Initiative (openapis.org), OAS / OpenAPI Specification (swagger.io), etc which may require even more publicly available forms of direct access and documentation.

Contact

Create and link to permanent contact Athennian page to include technical product support information, etc. Duplicate and timestamp the content, and also have an AI backup.

License

No context required here.

Terms of Service

No context required here.

Endpoints

Also know as the URL or location, the primary endpoints may be specific to your location (US) and type (sandbox/testing, etc).

HTTPS is required.

Headers

Additional headers may be relevant such as Content-Type (application/json unless otherwise noted), Cookie, etc.

API Keys

Moving to Headers & Contact above.

REST

🔗 This heading has no context required here.

Operations

🔗 This heading has no context required here.

Types

Inputs & Fields

We may soon separate and alphabetize required / non-nullable and unrequired / nullable Inputs and Fields directly in the type definitions or in the Example code snippets.

You may also find the Mapping section below helpful.

Errors

Here we'll begin to publish the most common validation response codes and primary context required to understand or resolve them as appropriate.

Mappings

Matching data between app API and the app GUI can vary primarily depending on customer configurations and requirements of Athennian and integrations. However, in generally the Read API examples below are valid for the following use cases.

Please note that the examples below do not show all API methods available. Also Write API syntax may vary.

Case Studies

Perhaps we'll add some of our oldest specific end-to-end API application examples here that illustrates most of the the information above together for those new to Athenniann, API, etc.