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. 

Reference catalogs let you define properties that behave like categories but which are defined at the domain 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 domain. 

Learn more:

• What are categories and reference catalogs?
• Create and configure Reference Catalog properties

This article is for AODocs super administrators who want to set up reference catalogs on their domain. It describes how to create a reference catalog with values.

Important:
– You must set up your reference catalogs by API.
– Reference catalogs are always single-level. You can't configure sublevels as you can for categories.

Learn more about what else you can do with reference catalogs using the API.

Automatically generated table of contents

Create reference catalogs

1. As a super administrator, follow one of these links to the referenceCatalog API:

• US instance:

https://apis-explorer.appspot.com/apis-explorer/?base=https://ao-docs.appspot.com/_ah/api#search/referencecatalog/referenceCatalog/v1/referenceCatalog.referenceCatalog.createReferenceCatalog

• EU instance:

https://apis-explorer.appspot.com/apis-explorer/?base=https://aodocs-core-eu-1.ey.r.appspot.com/api#search/referencecatalog/referenceCatalog/v1/referenceCatalog.referenceCatalog.createReferenceCatalog

Note: Dedicated instances have their own URLs. Learn more: What are AODocs instances?

Learn more: What are AODocs instances?

2. Enter the name of the reference catalog you want to create, for example, Country.

3. 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 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 domain.

1. As a super administrator, follow one of these links to the referenceCatalog API:

• US instance:

https://apis-explorer.appspot.com/apis-explorer/?base=https://ao-docs.appspot.com/_ah/api#search/referencecatalog/referenceCatalog/v1/referenceCatalog.referenceCatalog.saveReferenceCatalogValues

• EU instance:

https://apis-explorer.appspot.com/apis-explorer/?base=https://aodocs-core-eu-1.ey.r.appspot.com/api#search/referencecatalog/referenceCatalog/v1/referenceCatalog.referenceCatalog.saveReferenceCatalogValues

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.

List the reference catalogs on your domain with their IDs

1. As a super administrator, follow one of these links to the referenceCatalog API:

• US instance:

https://apis-explorer.appspot.com/apis-explorer/?base=https://ao-docs.appspot.com/_ah/api#search/referencecatalog/referenceCatalog/v1/referenceCatalog.referenceCatalog.getReferenceCatalogs

• EU instance:

https://apis-explorer.appspot.com/apis-explorer/?base=https://aodocs-core-eu-1.ey.r.appspot.com/api#search/referencecatalog/referenceCatalog/v1/referenceCatalog.referenceCatalog.getReferenceCatalogs

Note: Dedicated instances have their own URLs. Learn more: What are AODocs instances?

2. Enter your domain 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 domain. 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:

https://apis-explorer.appspot.com/apis-explorer/?base=https://ao-docs.appspot.com/_ah/api#search/referencecatalog/referenceCatalog/v1/

• EU instance:

https://apis-explorer.appspot.com/apis-explorer/?base=https://aodocs-core-eu-1.ey.r.appspot.com/api#search/referencecatalog/referenceCatalog/v1/

Note: Dedicated instances have their own URLs. Learn more: What are AODocs instances?

The referenceCatalog API has the following methods.