API V2

Details and resources for using the API v2.1

NULL values

Each endpoint has 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.

No records found

If no records are found for a GET request, a 400 Bad Request response is returned.

Versioning

To specify the version in your API request header:

api-version: 2.1

Available versions

  • v2.1 - The official and recommended version to use. Default if no version header is provided.

  • v2.0

Pagination

Pagination can be controlled with the query parameters pageNumber and pageSize (number of records on each page). There's a current limit of 100 records per page.

Example:

https://api.sandbox.younium.com/Subscriptions?pageSize=25&pageNumber=2

OrderBy

The request can be ordered by ascending or descending, and by one or more field names.

Example of ordering a GET subscriptions request by descending order number:

https://api.sandbox.younium.com/Subscriptions?orderby=orderNumber desc

Example of the same request but ordering first by ascending effective start date, and then by descending order number:

https://api.sandbox.younium.com/Subscriptions?orderby=effectiveStartDate asc, orderNumber desc

Filter

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.

Equality operators:

  • eq: ( == ) Test if a field is equal to a value.

  • ne: ( != ) Test if a field is not equal to a value.

Range operators:

  • 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.

Logical operators

  • and: Test if two statements are true.

  • or: Test if one of the two statements is true.

String value

Single quotation marks ( 'string' ) must be used when passing a string as a constant

Example:

https://api.sandbox.younium.com/Subscriptions?filter=status eq 'Active'

Datetime and guid values

Fields that are of type guids/uuid or datetime will need to be specified by type in the following way. Important to note the lower casing on the type.

Example for date:

https://api.sandbox.younium.com/Subscriptions?filter=modified gt datetime'2023-04-01'

Example for guid/uuid:

https://api.sandbox.younium.com/Accounts?filter=invoiceBatchGroupId eq guid'f68a9sa3-ff43-4f95-44b4-08f84be1dda4'

Nested objects

It is possible to filter on nested fields by using {fieldName}/{nested fieldName}. Important to note is that this will not work for a calculated field, If the field name is null, and for filtering lists. This also includes filtering on custom fields, which is not possible.

Example of only returning subscriptions with a CMRR amount between 100 and 1000:

https://api.sandbox.younium.com/Subscriptions?filter=cmrr/amount ge 100 and cmrr/amount le 1000

Multiple conditions

Logical operators can be used to chain multiple conditions in a query, like in the example above. Parentheses "( )" are used to nest conditions to ensure the logic is applied in the correct order.

Example:

https://api.sandbox.younium.com/Accounts?filter=inactive eq false and (defaultDeliveryAddress/country eq 'Norway' or defaultDeliveryAddress/country eq 'Sweden')

String Functions

For string values it is possible to use some extended functionality to filter on strings that start with, end with, or contain (substringof) a string segment. These functions replace the condition pattern [fieldName] [operator] [value]. Important to use lower casing on the function names.

Examples:

https://api.sandbox.younium.com/ChartOfAccounts?filter=startswith(code, '3')

https://api.sandbox.younium.com/Accounts?filter=endswith(invoiceEmailAddress, 'company.com')

//Filter for products include 'service' in its name. Note the value is the first argument and the field name the second 
https://api.sandbox.younium.com/Products??filter=substringof('service', name)

Modified after and modified before

As the filter is only applied to the top level of the entity structure, querying entities that have been modified before or after a specific date may not always be accurate. Eg a subscription may have a charge or a custom field which have been modified after the subscription. In these cases, the modifiedAfter and modifiedBefore parameters can be used as they apply the modified filter on all sub-levels of the entity. Each filter is applied as a or statement returning any entity where a modified match is found, returning only results where at least one of the entity or sub entities has been modified within the specified date and time.

Which sub-entities that are affected by these filters will be specified in the parameter description on the API reference. Worth noting that even though the filter is applied on all specified objects, some entities, like custom fields and price details, don’t have the modified field mapped.

Examples:

https://api.sandbox.younium.com/Subscriptions?modifiedAfter=2023-11-01

https://api.sandbox.younium.com/Subscriptions?modifiedBefore=2023-01-01

https://api.sandbox.younium.com/Subscriptions?modifiedAfter=2023-06-01&modifiedBefore=2023-12-01

LookupKey Identifier

In the request body of POST and PATCH there is sometimes a need to identify or reference related 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
//or
  "account": "8621d3c5-473e-41f1-f394-08d9dfc48d99" //identifying by uuid/guid
  "description": "New Subscription",
  "effectiveStartDate": "2022-07-15", 
  ...
}

By setting the field with key-value-pair-objectand in thekeySpecifying what property to identify against makes it possible to match with a wider range of properties. The following example is using key-value-pair matching with the name of the Account:

{
  "account": {
    "key": "name",
    "value": "ExampleAccount"
  }
  "description": "New Subscription",
  "effectiveStartDate": "2022-07-15", 
  ...
}

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.

If a custom field is used as a key, it is simply specified by its key property.

{
  "account": {
    "key": "customFieldKey",
    "value": "custom value 1"
  }
  ...
}
PreviousDeveloper resourcesNextData export API

Last updated

Was this helpful?