This guide describes how to request additional properties from the API. You will learn to modify your requests to include:

properties from related objects
properties from distantly related objects
additional properties on all objects in a list
properties that aren’t included by default in a response

How it works

The Ophelos API is organised into resources represented by objects with state, configuration, and contextual properties. These objects have unique IDs that you can use to retrieve, update, and delete them. The API also uses these IDs to link related objects together. A Debt, for example, links to a Customer by Customer ID.

{
  "id": "deb_m8kAKdMay0wt2G3xe0OJQv4r",
  "object": "debt",
  //...
  "customer": "cus_9dJo13AXOeYtENnOzrZRLjak",
  //...
}

In cases where you need information from a linked object, you can retrieve the linked object in a new call using its ID. However, this approach requires two API requests to access just one value. If you need information from multiple linked objects, each would also require separate requests, which all adds to the latency and complexity of your application.

The API has an Expand feature that allows you to retrieve linked objects in a single call, effectively replacing the object ID with all its properties and values. For example, you say you want to access details on a customer tied to a given Debt. You would retrieve the Debt and pass the debt property to the expand array, which tells Ophelos to include the entire Customer object in the response:

curl --request GET \
     --url 'https://api.ophelos.dev/debts/DEBT_ID?expand[]=customer' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer API_KEY'

Which returns the Debt with the full Customer object instead of its ID:

{
  "id": "deb_m8kAKdMay0wt2G3xe0OJQv4r",
  "object": "debt",
  //...
  "account_number": "001_6631962970",
  "customer": {
    "id": "cus_9dJo13AXOeYtENnOzrZRLjak",
    "object": "customer",
    //...
    "metadata": { }
  },
  //...
  "metadata": {}
}

Expanding multiple properties

To expand multiple properties in one call, add additional items to the expand array. For example, if you want to expand customer and the line_items for a given Debt, you would pass expand and array with both customer and line_items strings:

curl --request GET \
     --url 'https://api.ophelos.dev/debts/DEBT_ID?expand[]=customer&expand[]=line_items' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer API_KEY'

Expanding multiple levels

If the value you want is nested deeply across multiple linked resources, you can reach it by recursively expanding using dot notation. For instances, if you need to know the type customer contact details that was returned with a Debt object, you would first retrieve the Debt, then retrive the customer, and then the customer contact details. With expand you can do this in one call:

curl --request GET \
     --url 'https://api.ophelos.dev/debts/DEBT_ID?expand[]=customer.contact_details' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer API_KEY'

Which returns the debt with the full customer and contact details instead of their IDs:

{
  "id": "deb_m8kAKdMay0wt2G3xe0OJQv4r",
  "object": "debt",
  //...
  "account_number": "001_6631962970",
  "customer": {
    "id": "cus_9dJo13AXOeYtENnOzrZRLjak",
    "object": "customer",
    "kind": "unknown",
    "full_name": "Joe Blogs",
    "first_name": "Joe",
    "last_name": "Blogs",
    "preferred_locale": "en-GB",
    "date_of_birth": "1990-01-03",
    "contact_details": [
      {
        "id": "ccd_eRW4dbaXO9rC2wVaLGyEjMJv",
        "object": "contact_detail",
        "type": "mobile_number",
        "value": "+44757000000",
        "primary": false,
        "usage": "permanent",
        "source": "client",
        "status": "unverified",
        "created_at": "2024-11-29T15:25:57.757Z",
        "updated_at": "2024-11-29T15:25:57.757Z",
        "metadata": {}
      }
    ],
    "debts": [
      "deb_m8kAKdMay0wt2G3xe0OJQv4r"
    ],
    "created_at": "2024-11-29T15:25:57.610Z",
    "updated_at": "2024-11-29T15:25:59.442Z",
    "metadata": { }
  },
  //...
  "metadata": {}
}

Using expansion with webhooks

You can't receive webhook events with properties auto-expanded. Objects sent in events are always in their minimal form. To access nested values in expandable properties, you must retrieve the object in a separate call within your webhook handler.