This article is for developers with a full understanding of how to work with our API.
Important note about the API explorer:
When you follow the link we provide to the API explorer, you'll see a red warning.
The API itself is not deprecated. It's the Google API explorer that is deprecated. All the processes described in our API articles function correctly and safely if you use this Google API explorer.
This article provides instructions for AODocs super administrators on how to use the AODocs API to set up and manage reference catalogs on their AODocs tenant. It explains how to create catalogs with multiple levels, add hierarchical values, list catalogs and their IDs, and access available API actions.
In this article:
Automatically generated table of contents
What does the API call do?
As a super administrator, you can use the API to create reference catalogs with values.
Reference catalogs let you define properties that behave like categories but which are defined at the tenant level. This means that users can access exactly the same set of properties that behave like categories with the same values in all libraries on your AODocs tenant.
Learn more:
Reference catalogs can be single-level or multi-level. Learn more: Best practices for multi-level reference catalogs.
Important: You must set up your reference catalogs by API.
Learn more about what else you can do with reference catalogs using the API.
Create reference catalogs
1. As a super administrator, follow one of these links to the referenceCatalog API:
- US instance:
- EU instance:
Note: Dedicated instances have their own URLs. Learn more: What are AODocs instances?
2. Enter the name of the reference catalog you want to create, for example, Country.
3. Optionally, if you want to create a multi-level catalog, you can define level names using the updateReferenceCatalog endpoint.
Add the levelNames array with ordered names for each level. For example: ["Continent", "Country", "Region", "City"].
4. Click Authorize and execute.
The response is displayed in the lower part of the screen. You can see the name and ID of your newly created reference catalog. It currently has no values.
Create values for single-level reference catalogs
Important: You must have the ID of the reference catalog for which you want to create values. If you have just created your reference catalog, you can recover its ID in the response to the call to create it. Otherwise, you can list the reference catalogs and IDs on your AODocs tenant.
1. As a super administrator, follow one of these links to the referenceCatalog API:
- US instance:
- EU instance:
Note: Dedicated instances have their own URLs. Learn more: What are AODocs instances?
2. In the catalogId field, enter the ID of the reference catalog for which you want to create values.
3. In the Request body field, select referenceCatalogValues in the add a property menu.
4. Click the green plus button to add an array element. A new add a property menu appears.
5. Select name in the drop-down menu.
6. Enter the value you want to add to your reference catalog, for example, France.
7. Optionally, you can define an ID for the value:
- Select id in the add a property menu.
- Enter an ID for your value, for example,
France33.
Note: An ID is automatically generated if you don't define one.
8. Repeat steps 4 to 7 as many times as you like to enter more values.
Tip: Alternatively, prepare a JSON file with all your values beforehand. Switch to Freeform editor and paste the content of your JSON file into the text field.
9. Click Authorize and execute. The response is displayed in the lower part of the screen.
Create values for multi-level reference catalogs
Important: You must have the ID of the reference catalog for which you want to create values. If you have just created your reference catalog, you can recover its ID in the response to the call to create it. Otherwise, you can list the reference catalogs and IDs on your AODocs tenant.
For multi-level catalogs, you need to specify parent-child relationships.
1. Follow steps 1 to 6 from the instruction on creating values for single-level reference catalogs.
2. For top-level values (no parent) add values without specifying a parent field.
These will be at level 0 in your hierarchy.
3. For child values:
- Add the parent property in the add a property menu.
- Enter the ID of the parent value. This assumes the parent value already exists.
- The system automatically calculates:
- The
level(incremented from parent's level) - The
parentIdsarray (chain of all ancestor IDs) - The
leafstatus of parent values
- The
Note: Before creating child values, the corresponding level must already exist in the reference catalog.
4. Optionally. set the display order:
- Add the rank property to control the display order.
- Enter a positive integer (lower numbers appear first)
By default, values are displayed in alphabetical order (A → Z). However, you can define a custom order by assigning a rank to each value.
If both ranked and unranked values are present, the ranked values will appear first, sorted according to their assigned ranks. The remaining unranked values will follow, sorted alphabetically.
Below is a JSON example for multi-level structure:
{"referenceCatalogValues": [ { "name": "Europe", "id": "europe" }, { "name": "France", "id": "france", "parent": "europe" }, { "name": "Paris", "id": "paris", "parent": "france" }, { "name": "Germany", "id": "germany", "parent": "europe" }, { "name": "Berlin", "id": "berlin", "parent": "germany" } ] }
Tip: For complex hierarchies, prepare a JSON file with all your values and their relationships beforehand. Switch to Freeform editor and paste the content of your JSON file into the text field.
5. Click Authorize and execute. The response is displayed in the lower part of the screen.
List the reference catalogs on your AODocs tenant with their IDs
1. As a super administrator, follow one of these links to the referenceCatalog API:
- US instance:
- EU instance:
Note: Dedicated instances have their own URLs. Learn more: What are AODocs instances?
2. Enter your AODocs tenant name.
3. Click Authorize and execute.
The response is displayed in the lower part of the screen. It lists all the reference catalogs on your AODocs tenant. Copy the ID of the reference catalog for which you want to create values.
Access the list of all actions available for managing your reference catalogs
As a super administrator, follow one of these links to the referenceCatalog API:
- US instance:
- EU instance:
Note: Dedicated instances have their own URLs. Learn more: What are AODocs instances?
The referenceCatalog API has the following methods.
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
Note: This is is different from marking a value as deleted. This permanently removes the value from the reference catalog |
Best practices for multi-level reference catalogs
- Plan your hierarchy: before creating values, map out your complete hierarchical structure to ensure consistency.
- Use meaningful IDs: create descriptive IDs for values that will help you identify parent-child relationships easily.
- Build top-down: create parent values before their children.
- Use bulk operations: for large hierarchies, prepare your entire structure in JSON format and upload it in a single operation.
- Consider performance: very deep hierarchies (more than 5 levels) may impact user interface performance – test your structure before full deployment.
- Maintain consistency: ensure all libraries on your AODocs tenant use the same reference catalog structure for consistent data management across your organization.