Get Basic Account Information

Short Description: Once you've established that you have a valid API ID, you'll need to call the my-account endpoint to get your basic account information.

JSON Calls documentation:

This object is comprised of the following simple objects:

Name Object Category Object Type Nullable Description
_href JSON Reference string 0

The URL to request that document from the API.
id CCH Structure integer 0

ID of the record.
address1 Content string 1

First address line.
address2 Content string 1

Second address line.
allowed builds Content integer 0

The number of builds left on the account.
allowed_tokens Content integer 0

The number of remaining tokens for use when sharing lists with other organizations.
city Content string 1

The city the address is located in.
country Content string 1

The country the address is located in.
date_created Content date 0

The date the record was created.
date_updated Content date 0

The date the record was updated.
domain CCH Structure string 1

Subdomain for the account on commoncontrolshub.com
groups JSON Reference URL 1

The URL to get the acount's groups.
hide_organization_name CCH Structure string 1

This hides the name of the organization in the header if it is set.
initiatives JSON Reference URL 1

The URL to get the acount's initiatives.
CCH Structure algorithm 1

This is the Base64encoded version of the account's logo.
mapper_training_seats CCH Structure integer 1

The number of purchased mapper training seats the account has left to use.
organization_name CCH Structure string 1

The name of the organization in the account.
postal_code Content string 1

The postal/zip code for the address.
reseller CCH Structure integer 0

Whether the organization is a reseller or not. If this is equal to the id, the account is a reseller. If it is not equal and not null, the account is managed by a reseller.
reseller_status CCH Structure integer

The status of the reseller. 1 = pending approval. 2 = approved.
roles JSON Reference URL

The URL to get the account's roles.
select_ads integer

NOT USED
state Content string

The state/province for the address.
status UCF Structure string

This field represents the status the document is in within the UCF’s document mapping process. The status fields are (in information flow order):

• Suggested meaning the document is at an early stage in the process. Much of the needed information is still missing but UCF staff are reviewing the document to decide if it should become “recommended” (see below).

• Recommended meaning the document has been recommended for inclusion in the UCF, but not yet verified.

• Queued meaning the document has been queued to be added to the UCF soon.

• In Research meaning the document is somewhere between being recommended and us figuring out what to do with it (or even find it in English).

• In Edit meaning the document is being worked on.

• Released meaning the document has been added to the UCF and should have an applicable release date.

• Not Applicable meaning the document has been verified to be a real authority document, however, the UCF mapping team have made the decision not to include the document in the UCF (for any number of reasons).

• On Hold Every so often we are sent an authority document for mapping that, during the mapping or research process, goes into change. Therefore, when that happens, we mark the authority document as being "On Hold" until we hear otherwise.

• Redacted means the record is no longer live. If the record belongs to an authority document (versus either a category record or originator record), then all the control citations within the UCF’s main tables will also be redacted.
time_created UCF Structure string

The date and time the record was created.
time_updated UCF Structure string

The date and time the record was last updated.
unspsc_code Content string

The United Nations product and service code most applicable to the record.
users JSON Reference URL

The URL to get the record's users.

Use Cases

Many aspects of API 2.0 deal with information found in the user’s account. Authority Document Lists are assigned to accounts, the API’s license date is assigned to the account, etc.

So you’ll want to get set up a structure to interpret the user account and put the data in the right structures within your system.

Prior to getting the APIs calls for an account, you’ll want to ensure that you’ve set up a basic account structure like the one in the diagram below.

Getting Account data

The first call you’ll make with the API sets up your basic account information. This includes a total of six tables:

  1. Account - the basics of the account, such as its address and organizational information. For more information about this table, including all of the fields associated with it, click HERE.
  2. Groups - each of the groups that your users have set up within the account, whether they are nested within other groups or initiatives is irrelevant for this table. For more information about this table, including all of the fields associated with it, click HERE.
  3. Initiatives - each of the initiatives that your users have set up within the account, whether they are nested within groups is irrelevant for this table. For more information about this table, including all of the fields associated with it, click HERE.
  4. Users - each of the Users within your account. For more information about this table, including all of the fields associated with it, click HERE.
  5. Roles - the various roles assigned within the Common Controls. For more information about this table, including all of the fields associated with it, click HERE.
  6. Authority Document (AD) Lists - the shared Authority Document lists that the user has chosen to send through to the API. For more information about this table, including all of the fields associated with it, click HERE.

What this doesn’t give you is detailed information about the groups found within groups or the initiatives found within initiatives. You’ll need a few more calls for that.