Understanding Queries

Queries are crucial in Gotransverse because your application will often need to retrieve information to create objects. For example, creating an order requires queries for bill cycle, billing account category, and product. Read below to learn the fundamentals of queries in Gotransverse. For detailed instruction, see the SOAP or REST getting started guides linked at the bottom of the page.

Query Keys

Queries can be as broad as "return all the billing accounts" and as specific as "return billing account with eid of "1557". Query Keys are parameters used as keys to filter query results. Most queries require a key to filter results. See the table of Query Keys for more information.

Logic Filters

The whereClause parameter adds an additional filter to query results. The whereClause allows you to specify a parameter within the entity and filter it using one or more relational expressions.

Example: <whereClause entityType="paymentTerm" clause="eid neq '134'"/> | Returns instances of the queried entity where the paymentTerm does not equal 134. Learn more: whereClause

Query Scope

Query Scope determines the depth of information returned in a query response. By default, queries are SHALLOW. A SHALLOW query will return attributes on the queried object, but will only return the EID of any elements within, and only the count of any collections. A DEEP query will return all attributes for the object AND the collections in the object.

Paging and Sorting

Some queries return numerous results. You can use the parameters orderBy, pageNumber, and pageSize to organize the results.

orderBy (attribute, ascending) orderBy Specifies the attribute to sort by and whether the results are ascending. Eid is the only supported parameter at this time.
pageNumber int The page number the results will start on.
pageSize int The number of objects returned in a page.

Query Tenant Settings

Setting Values (default) Description
Allow the API to return deep query results True / False Allow the API to return complete children objects of a queried object.
Default API Query Scope Shallow / Deep The default value for the API queryScope attribute for this tenant.
Max Number of API Entities Returned in Query Response 50 Maximum number of top level entities allowed in an API query response.

Error Codes

401 Unauthorized Double-check your authentication.
500 An EntityType must be specified in a query request. Enter a valid entity in <type></type>.
500 The specified type: 'queried entity' does not support an empty parameter set Add a parameter and value: <parameter parameter=" " parameterValue=" "/>
500 Unmarshalling Error: Unexpected 'character' in attribute value at [row,col {unknown-source}]: [row ,column] Correct the character at the specified location.
500 Mismatched input input characters expecting expected datatype Check the datatype you're trying to enter; strings are double quoted, unless in a clause, where they are single quoted.

Related Topics

Query Keys

Getting Started with REST

Getting Started with SOAP