1. U4 ERPx
  2. API Reference
  3. ObjectAPI
  4. Schema

Schema

Investigating the structure/schema of an ObjectAPI endpoint

Introduction

While we can use the OpenAPI specification to learn about how the response on a certain ObjectAPI endpoint would look like, there are a few responses that might be different depending on the current companyId and/or the rights of the caller. The same case applies for custom fields (also known as Flexi-fields). Therefore, requesting the schema helps a lot in this matter.

The schema can be requested by preparing a regular request, and providing the request header Accept: application/schema+json as shown below.

Sample

curl -X GET \
  "https://unit4-api-address/v1/objects/customers\
        ?companyId=EN\
        &select=companyId,customerId,customerName,invoice(creditLimit,currencyCode)\
        &filter=customerId eq '10000'" \
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -H "Accept-Encoding: gzip" \
    -H "Accept: application/schema+json"
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "definitions": {},
    "type": "object",
    "properties": {
        "companyId": {
            "type": "string",
            "x-u4-attribute": {
                "attributeId": "A3",
                "metadata-link": {
                    "ref": "/v1/objects/attributes?companyId={companyId}&filter=attributeId+eq+%27A3%27",
                    "templateRequired": [
                        "companyId"
                    ]
                },
                "link": {
                    "ref": "/v1/objects/attribute-values?companyId={companyId}&filter=attributeId+eq+%27A3%27",
                    "templateRequired": [
                        "companyId"
                    ]
                }
            },
            "x-u4-describable": true,
            "x-u4-mandatory": true,
            "x-u4-filterable": true,
            "x-u4-connectedentity": "Company2",
            "x-u4-description": "Client Code [from attribute CLIENT]"
        },
        "customerId": {
            "type": "string",
            "x-u4-attribute": {
                "attributeId": "A4",
                "metadata-link": {
                    "ref": "/v1/objects/attributes?companyId={companyId}&filter=attributeId+eq+%27A4%27",
                    "templateRequired": [
                        "companyId"
                    ]
                },
                "link": {
                    "ref": "/v1/objects/attribute-values?companyId={companyId}&filter=attributeId+eq+%27A4%27",
                    "templateRequired": [
                        "companyId"
                    ]
                }
            },
            "x-u4-describable": true,
            "x-u4-mandatory": true,
            "x-u4-filterable": true,
            "x-u4-connectedentity": "customers_1",
            "x-u4-description": "Customer Id [from attribute CUST.ID]"
        },
        "payment": {
            "type": "object",
            "properties": {
                "bankAccount": {
                    "type": "string",
                    "x-u4-filterable": true,
                    "x-u4-description": "show blank if bank account is a dummy. Otherwise shows bank account"
                }
            }
        }
    },
    "x-u4-keys": "companyId,customerId",
    "x-u4-attribute": {
        "attributeId": "A4",
        "metadata-link": {
            "ref": "/v1/objects/attributes?companyId={companyId}&filter=attributeId+eq+%27A4%27",
            "templateRequired": [
                "companyId"
            ]
        },
        "link": {
            "ref": "/v1/objects/attribute-values?companyId={companyId}&filter=attributeId+eq+%27A4%27",
            "templateRequired": [
                "companyId"
            ]
        }
    },
    "x-u4-description": "Party placing the order or paying the invoice"
}

We can control the returned properties that are present in the schema as described below:

Omitting the select Query Parameter

Returns schema information for properties

Providing * for the select Parameter

The same way as for a normal request, can be combined with naming properties explicitly: *,lastUpdated(*)

Providing *.* for the select Parameter

This is an additional feature compared to the regular requests. It provides the same schema information as when the select query parameter is omitted, but additionally includes ContactPoints, Custom FieldGroups, and RelatedValues if applicable. This feature is a great help for investigating the available CustomFields structure. It also includes possible associations at multiple depths.

OpenAPI Schema Definition for CustomFields

For investigating the received schema, we can make the request as shown below, where the endpoint returns the properties age and link_fx from the custom field group:

/v1/objects/customers?filter=customerId eq '1010'&filter=contains(customerName, 'Mar')&select=companyId,customerId,customerName,contactPoints(*,address(*),additionalContactInfo(contactPerson))
... returns...
[{
    "companyId": "EN",
    "customerId": "090909",
    "customFieldGroups": {
        "mfa": {
            "age": 0,
            "link_fx": "News"
        }
    }
}]