API Documentation

Querying Accounts & Locations

In this guide:

• Introduction
• Prerequisites
• Querying accounts
• Querying locations

Introduction

One of the purpose of retrieving Accounts and Location IDs is to include this additional information when creating(or updating) a purchase order.

Prerequisites

To be able to query Account & Account's Locations, you would need to provide your account UUID.

Querying Accounts

To be able to see the list of accounts, we will perform the following Accounts query in API.

POST /graphql
Query

query assignableAccounts($accountId: String!, $searchAssignableAccountsFiltersInput: SearchAssignableAccountsFiltersInput!) {
  searchAssignableAccounts(accountId: $accountId, searchAssignableAccountsFiltersInput: $searchAssignableAccountsFiltersInput) {
    nodes {
      account {
        id
        tradingName
        label {
          short
          long
        }
      }
    }
    totalCount
  }
}

Assignable Accounts Query Options

You can use the following options to query accounts:

• connectionType (String):

  • 'SUPPLIER' - Returns only supplier accounts.

• excludeAccountId (UUID):

  • The account ID to exclude from the results.

• searchQuery (String):

  • A string used to search for accounts. This allows filtering based on partial or full account matches.

Example Usage

Use these options in combination to filter location data according to specific account, company, and location parameters. If any option is omitted, defaults will be applied to return a comprehensive result.

{
  "accountId": "YOUR_ACCOUNT_UUID",
  "searchAssignableAccountsFiltersInput": {
    "connectionType": "SUPPLIER",
    "searchQuery": "supplier"
  }
}

Mandatory variable is account ID which was provided when you started using the API.

Variables

{
  "accountId": "YOUR_ACCOUNT_UUID"
}

or with extra filtering, where ids and searchQuery are filtering locations, variables would look like below:

{
  "accountId": "YOUR_ACCOUNT_ID"
}

The result of our query returns list containing all locations ids with relevant data. An example of the response is:

JSON response

{
  "data": {
    "searchAssignableAccounts": {
      "nodes": [
        {
          "account": {
            "id": "38261bb5-ba5a-4f20-a893-da399617953e",
            "tradingName": "Supplier 1",
            "label": {
              "short": "Supplier 1",
              "long": "Supplier 1"
            }
          }
        }
      ],
      "totalCount": 1
    }
  }
}

Querying Locations

To be able to see the list of locations, we will perform following Locations query in API console. How to perform GraphQL queries you can read more here.

POST /graphql
Query

query accountLocations($accountId: String!, $accountLocationsFiltersInput: AccountLocationsFiltersInput) {
    accountLocations(
        accountId: $accountId
        accountLocationsFiltersInput: $accountLocationsFiltersInput
    ) {
        nodes {
            id
            label {
                short
                long
            }
            address {
                line1
                line2
                postalCodeOrZip
                city
                countyOrState
                country {
                    code
                    name
                }
            }
            timeZone
        }
        edges {
            node {
                id
                label {
                    short
                    long
                }
                address {
                    line1
                    line2
                    postalCodeOrZip
                    city
                    countyOrState
                    country {
                        code
                        name
                    }
                }
                timeZone
            }
        }
        pageInfo {
            startCursor
            endCursor
            hasNextPage
        }
    }
}

Locations Query Options

You can use the following options to query account locations:

• accountIds (List of UUIDs):

  • A list of account IDs to filter the locations.

• companies (List of Strings):

  • A list of company names to filter the locations by.

• hqOnly (Boolean):

  • If true, only Headquarters (HQ) locations will be returned. Defaults to false.

• includeArchived (Boolean):

  • If true, archived locations will be included in the result set. Defaults to false.

• searchQuery (String):

  • A string used to search for location addresses. This allows filtering based on partial or full address matches.

• source (OWNED, MANAGED, NON_MANAGED):

  • Filters locations based on their source type. If not provided, all source types will be returned.

• usageContexts ( BOTH, SHIP_FROM, SHIP_TO):

  • Defines the context in which the locations are used. If not provided, all usage contexts will be returned.

Example Usage

Use these options in combination to filter location data according to specific account, company, and location parameters. If any option is omitted, defaults will be applied to return a comprehensive result.

{
  "accountId": "YOUR_ACCOUNT_ID",
  "accountLocationsFiltersInput": {
    "accountIds": [],
    "companies": [],
    "hqOnly": false,
    "includeArchived": false,
    "searchQuery": "some text",
    "source": "OWNED",
    "usageContexts": "BOTH"
  }
}

Mandatory variable is account ID which was provided when you started using the API.

Variables

{
  "accountId": "YOUR_ACCOUNT_UUID"
}

or with extra filtering, where ids and searchQuery are filtering locations, variables would look like below:

{
  "accountId": "YOUR_ACCOUNT_ID",
  "searchQuery": "some text"
}

The result of our query returns list containing all locations ids with relevant data. An example of the response is:

JSON response

{
  "data": {
    "accountLocations": {
	"nodes": [
	  {
	    "id": "6c12cb9a-bd20-404c-ab60-9a6e1d12af13",
	    "label": {
		"short": "Zencargo, Zencargo",
		"long": "Zencargo, Zencargo, 6th Floor, Thavies Inn House Holborn Circus, Thavies Inn, London, EC1N 2HA, United Kingdom"
	    },
	    "address": {
		"line1": "6th Floor, Thavies Inn House Holborn Circus, Thavies Inn",
		"line2": "",
		"postalCodeOrZip": "EC1N 2HA",
		"city": "London",
		"countyOrState": "",
		"country": {
		  "code": "GB",
		  "name": "United Kingdom"
		}
	    },
	    "timeZone": "Europe/London"
	  }
	],
	"edges": [
	  {
	    "node": {
		"id": "6c12cb9a-bd20-404c-ab60-9a6e1d12af13",
		"label": {
		  "short": "Zencargo, Zencargo",
		  "long": "Zencargo, Zencargo, 6th Floor, Thavies Inn House Holborn Circus, Thavies Inn, London, EC1N 2HA, United Kingdom"
		},
		"address": {
		  "line1": "6th Floor, Thavies Inn House Holborn Circus, Thavies Inn",
		  "line2": "",
		  "postalCodeOrZip": "EC1N 2HA",
		  "city": "London",
		  "countyOrState": "",
		  "country": {
		    "code": "GB",
		    "name": "United Kingdom"
		  }
		},
		"timeZone": "Europe/London"
	    }
	  }
	],
	"pageInfo": {
	  "startCursor": "MA==",
	  "endCursor": "MA==",
	  "hasNextPage": false
	}
    }
  }
}