Developer resources

API environment base URLs

Sandbox: https://apisandbox.younium.com

Production: https://api.younium.com

Using the API

The Younium API is a rest API using json data. In general, the following Http verbs are used:

  • GET: Read

  • POST: Create

  • PATCH: Update

  • DELETE: Delete

Patching data

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

NULL values

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.

API versioning

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.

    • Pagination

    • Filter

    • OrderBy

To specify the version in your API request header:

api-version: 2.1

Query Parameters (for version 2.1)

Pagination

Pagination can be set with pageNumber and pageSize (number of records on each page). The pageSize have a limit of 100 records per page.

Example:

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

OrderBy

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:

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

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

Filter

A filter can be added to a request returning only records that pass certain tests.

?filter=[fieldName] [operator] [constant]

The following operators can be used to test records.

Equality operators:

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

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

Range operators:

  • gt: ( > ) Test if a field is greater than a constant value.

  • lt: ( < ) Test if a field is  less than a constant value.

  • ge: ( >= ) Test if a field is greater than or equal to a constant value.

  • le: ( <= ) Test if a field is less than or equal to a constant value.

Logical operators

  • and: Test if two statements are true.

  • or: Test if one of two statements are true.

String constants

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

Example:

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

Nested objects

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

LookupKey Identifier

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 define to what Account it belongs. 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 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:

{
  "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.

Webhooks

Webhooks are used to build near realtime integrations with API's and other Saas services. When a business event happens in Younium, an event is placed in a queue that when executed will notify subscribers with a HTTP POST request. The request contains relevant information about the business event for the subscriber to use in the receiving system/platform.

An alternative to Webhooks is to make scheduled API requests on a frequent basis, using Webhooks is more efficient and normally provides a much better user experience.

What business are supported by Webhooks:

At this point, the following endpoints are implemented:

  • Subscription Created

  • Subscription Changed

  • Subscription Cancelled

  • Subscription Renewed

  • Subscription Updated

  • Invoice Posted

  • Journal Posted

  • Account Created

  • Account Changed

How to register a Webhook to your service

To register a Webhook you make a POST request to the Webhooks endpoint.

The Webhooks endpoint take two parameters in the body: URL and Events. Events is a list of Event Tags, see Event tags in the table above.

Example (Sandbox):

POST https://apisandbox.younium.com/Webhooks

Headers:

Authorization: Bearer [JWT token] 
Content-Type: application/json

Body:

{ 
  "url": "URL TO YOUR SERVICE", 
  "events": [ "InvoicePosted" ] 
}

Webhooks may be deleted with a DELETE operation on the same endpoint.