API environment base URLs
Using the API
The Younium API is a rest API using json data. In general, the following Http verbs are used:
Updates to data in Younium are made using the concept of patching. This means that only the data (fields) provided in the patch request are updated in the target entity, all other fields on the entity remains as they were (except when a change of a field triggers changes to other fields, such as calculated/aggregated values, statuses, etc.).
Each endpoint have a schema with fields that will populate the response if there is a value. However when the response data is created there may be fields that have no value, which are null. These Fields are excluded from the JSON response. In other words only fields containing values are present in the response.
The API have two versions with some differences.
Features of version 2.0
All records of en entity are fetched.
Responses containing multiple records are returned as a List and as an empty list if no records was found.
Features of version 2.1
Responses containing multiple records are returned and wrapped in a paginated response providing 1 -100 entries per page.
If no entries are found a 400 Bad Request response is returned.
Query parameter functionality.
To specify the version in your API request header:
Query Parameters (for version 2.1)
Pagination can be set with pageNumber and pageSize (number of records on each page). The pageSize have a limit of 100 records per page.
The request can be ordered either ascending or descending by one or more field names.
Example of ordering a GET subscriptions request by descending order number:
Example of the same request but ordering first by ascending effective start date, and then after descending order number:
https://apisandbox.younium.com/Subscriptions?orderby=effectiveStartDate asc, orderNumber desc
A filter can be added to a request returning only records that pass certain tests.
?filter=[fieldName] [operator] [value]
The following operators can be used to test records.
eq:( == ) Test if a field is equal to a value.
ne:( != ) Test if a field is not equal to a value.
gt: ( > ) Test if a field is greater than a value.
lt:( < ) Test if a field is less than a value.
ge:( >= ) Test if a field is greater than or equal to a value.
le:( <= ) Test if a field is less than or equal to a value.
and: Test if two statements are true.
:Test if one of two statements are true.
Single quotation marks (
'string' ) must be used when passing a string as a constant
https://apisandbox.younium.com/Subscriptions?filter=status eq 'Active'
Datetime and guid values
Fields that are guids/uuid or datetimes will need to specified by type like in the following examples. Important to note the lower casing on the type.
Example for DateTimes:
https://apisandbox.younium.com/Subscriptions?filter=modified gt datetime'2023-04-01'
Example for Guid:
https://apisandbox.younium.com/Accounts?filter=invoiceBatchGroupId eq guid'f68a9sa3-ff43-4f95-44b4-08f84be1dda4'
It is possible to test nested objects of a request by using
'[fieldName]/[nested fieldName]'. Important to note is that this will not work on Lists or if a fieldName is null.
Example of only returning subscriptions with a CMRR amount between 100 and 1000:
https://apisandbox.younium.com/Subscriptions?filter=cmrr/amount ge 100 and cmrr/amount le 1000
The logical operators can be used to chain multiple conditions in a query like in the example above. The parentheses "( )" can also be used to nest conditions to ensure the logic is applied in the correct order.
https://apisandbox.younium.com/Accounts?filter=inactive eq false and (defaultDeliveryAddress/country eq 'Norway' or defaultDeliveryAddress/country eq 'Sweden')
For string values it is possible to use some extended functionality to filter on strings that starts with, ends with or contains (substringof) a string segment. These functions replace the condition pattern [fieldName] [operator] [value]. Important to use lower casing on the function names.
//Filter for products include 'service' in its name. Note the value is the first argument and the field name the second
In the request body of POST and PATCH there is sometimes a need identify or reference relating entities, eg. when creating a Subscription we want to define what Account it belongs to or what Currency to use. Fields like this are of the type
LookupKeyand can accept both a
uuid/Guid, a String and a key-value-pair-object.
Examples of lookupKey-value as a string to set the field account:
"account": "A-000001", //using a string to identify by accountNumber
"account": "8621d3c5-473e-41f1-f394-08d9dfc48d99" //identifying by uuid/guid
"description": "New Subscription",
By setting the field with
key-value-pair-objectand in the
keyspecifying what property to identify against it is possible to match with a wider range of properties.
The following example is using key-value-pair matching with the name of the Account:
"description": "New Subscription",
The LookupKey will try to match the values that are set against the field entity. If no matches are found or if there are multiple matches found a Bad Request will be returned.