# Introduction > **Important**: This is a living document and is subject to change. Please refer to the [Changelog](#section/Changelog) for updates. > If you find a Typo, of something that doesn't make sense, please let us know by raising an issue. The Ophelos API provides access to the Ophelos platform for managing debts and customers. The Ophelos API is organised around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. You can use the Ophelos API in staging mode, which does not affect your live data. The URL used for the request determines whether the request is live or staging. The Ophelos API doesn't support bulk updates. You can work on only one object per request. The Ophelos API differs for every account as we release new versions and innovate our services. # Authorization Ophelos supports [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749) for authorizing API requests. The OAuth framework provides several grant types for different use cases. In the *Machine To Machine* communication, we use the [Client Credentials Grant Type](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/) In summary, authorized requests to the API should use an `Authorization` header with the value `Bearer `, where `` is an access token obtained through the OAuth flow. ```shell curl https://api.ophelos.com/debts \ -H "Authorization: Bearer " ``` The access token is a string that contains the credentials and permissions needed for an application to access protected resources. ## Request an access token First obtain your **Client ID**, **Client Secret** and **Audience** by contacting our development team. Once you have the client credentials, you can request an access token through our token endpoint URI. ```shell curl --request POST \ --url 'https://id.ophelos.com/oauth/token' \ --data grant_type=client_credentials \ --data client_id={YOUR_CLIENT_ID} \ --data client_secret={YOUR_CLIENT_SECRET} \ --data audience={YOUR_API_IDENTIFIER} --date scope={API_PERMISSION_IF_EXISTS} ``` ### Parameters | Parameter Name | Relevance | Description | | ---- | ------ | ----------- | | grant_type | Required | Set this to "client_credentials" | | client_id | Required | Your application's Client ID | | client_secret | Required | Your application's Client Secret | | audience | Required | Your application's Identifier | | scope | Optional | The scopes which you want to request authorization for | ### Response ```json { "access_token": "eyJz93a...k4laUWw", "token_type": "Bearer", "expires_in": 3600 } ``` # Expanding Responses Many object allow you to request additional information as an expanded response by using the `expand` request parameter. This parameter is available on all all API requests, and applies to the response of that request only. In many cases, an object contains the ID of a related object in its response properties. For example, a `Payment` might have an associated Debt ID. You can expand these objects in line with the expand request parameter. The `expandable` label in this documentation indicates ID fields that you can expand into objects. Performing deep expansions on numerous list requests might result in slower response times. You can expand multiple objects at the same time by identifying multiple items in the `expand` array. ```shell curl https://api.ophelos.com/payments?expand[]=debt -H "Authorization: Bearer sk_prod_H4x0rN0t4R3alAPiK3y" ``` ```json { "id": "pay_123", "object": "payment", ... "debt": { "id": "debt_123", "object": "debt", ... } } ``` # Errors Ophelos uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the `5xx` range indicate an error with Ophelos's servers. | Code | Status | Description | | ---- | ------ | ----------- | | 200 | OK | Everything worked as expected. | | 400 | Bad Request | The request was unacceptable, often due to missing a required parameter. | | 401 | Unauthorized | No valid API key provided. | | 403 | Forbidden | The API key doesn't have permissions to perform the request. | | 404 | Not Found | The requested resource doesn't exist. | | 409 | Conflict | The request could not be completed due to a conflict with the current state of the resource. | | 422 | Unprocessable Entity | The parameters were valid but the request failed. | | 429 | Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. | | 500, 502, 503, 504 | Server Errors | Something went wrong on Ophelos's end. (These are rare.) | # Metadata Updatable Ophelos objects—including Debts, Customers, and Organisations has a `metadata` parameter. You can use this parameter to attach key-value data to these objects. You can use metadata to store additional, structured information on an object. For example, you could store your own unique identifier from your system for the object. Ophelos doesn't use this data for its own purposes, but you can retrieve it when you retrieve the object. It is not displayed to customers. ```shell curl https://api.ophelos.com/debts \ -u sk_prod_H4x0rN0t4R3alAPiK3y: \ -d "metadata[case_id]=3012345" ``` ```json { "id": "deb_123", ... "metadata": { "case_id": "3012345" } } ``` Some objects support a `description` parameter. You can use `description` parameter to annotate the object with a human-readable description. This is displayed to customers. Do not store any sensitive information (customer bank details, etc.) in the metadata field. ## Sample metadata use cases - **External IDs:** Attach your system's unique IDs to a object to simplify lookups. For example, you could store your customer ID in the `metadata` field of a customer object. # Pagination All top-level API resources have support for bulk fetches through "list" API methods. For example, you can [list debts](/#operation/listDebts), [list customers](/#operation/listCustomers), and [list organisations](/#operation/listOrganisations). Search endpoints also support pagination. These list API methods share common structure and accept, at a minimum, the following parameters: `limit`, `after`, and `before`. Ophelos's API methods use cursor-based pagination through the `after` and `before` parameters. Both parameters accept an existing object ID value and return objects in reverse chronological order. The `before` parameter returns objects listed before the named object. The `after` parameter returns objects listed after the named object. These parameters are mutually exclusive. You can use either the `before` or `after` parameter in a request, but not both simultaneously. Headers for pagination are included in the response, providing information about the total number of objects in the list and the URL for the next and previous pages. ## Example pagination ```shell curl https://api.ophelos.com/debts?limit=3 -H "Authorization: Bearer sk_prod_H4x0rN0t4R3alAPiK3y" \ -I ``` ``` HTTP/1.1 200 OK Link: ; rel="first", ; rel="next", ; rel="prev" X-Total-Count: 34 X-Page-Items: 10 ``` # Versioning When backwards-incompatible changes are made to the API, we release a new, dated version. Learn more about API updates, view our API changelog. By default, requests made with cURL use your Ophelos account's default API version unless you override it by setting the `Ophelos-Version` header. Webhook events also use your account's API version by default. You can upgrade your API version in the Ophelos Terminal. ```shell curl https://api.ophelos.com/debts \ -H "Ophelos-Version: 2024-05-08" ``` ## Backwards-compatible changes Ophelos considers the following changes to be backwards-compatible: - Adding new API resources. - Adding new optional request parameters to existing API methods. - Adding new properties to existing API responses. - Changing the order or properties in existing API responses. - Changing the length or format or opaque strings, such as object IDs, error messages, and other human-readable strings. - Adding new event types. - Make sure that your webhook listener gracefully handles unfamiliar event types. # Domains and IP addresses Ensure your integration is always communicating with Ophelos. Your integration must be able to reach any of Ophelos's fully quality [domain names](#section/Domains-and-IP-addresses/Domains) for it to function properly. Depending on how your integration operates, you may need to add them to an allowlist. To help your integration operate securely, it must also verify that it's communicating with api.ophelos.com through one of our listed [IP addresses](#section/Domains-and-IP-addresses/IP-addresses). ## Domains Ophelos uses the following fully qualified domain names to interact with your integration: api.ophelos.com api.ophelos.dev ## IP addresses ### API The full list of IP addresses that api.ophelos.com may resolve to is: 35.71.181.159 15.197.132.132 The following IP addresses are used by api.ophelos.dev (staging environment): 3.33.255.246 15.197.227.99 ### Webhooks and outbound You might need to whitelist the following IP addresses to receive webhooks and outbound communication from Ophelos the full list of IP addresses used for performing outbound API calls and delivering webhooks from api.ophelos.com: 3.248.44.20 63.32.212.209 3.125.152.60 3.127.78.75 35.156.118.202 the full list of IP addresses used for performing outbound API calls and delivering webhooks from api.ophelos.dev (staging environment): 18.202.140.252 54.76.168.95 63.33.234.57 Remember, IP addresses may change over time. Keep this documentation handy and check back for updates to ensure uninterrupted service. # Search Some top level API resources support retrieval with search API methods. You can use the search APIs to retrieve your Stripe objects in a flexible manner. Using search is a faster alternative to paginating through all resources. To create a search query, review the Search query language and reference the query fields of the sub-resource: - [Query for Customers](#section/Search/Supported-query-fields-for-each-resource/customers) - [Query for Debts](#section/Search/Supported-query-fields-for-each-resource/debts) - [Query for Payments](#section/Search/Supported-query-fields-for-each-resource/payments) - [Query for Invoices](#section/Search/Supported-query-fields-for-each-resource/invoices) ## Examples Here are some examples of search queries you can use with the search API methods: #### Debt metadata search ```shell curl -G https://api.ophelos.com/debts \ -u sk_prod_H4x0rN0t4R3alAPiK3y: \ --data-urlencode "query=metadata['case_id']:'3012345'" ``` #### Customer email search Lookup customers matching an email. ```shell curl -G https://api.ophelos.com/customers \ -u sk_prod_H4x0rN0t4R3alAPiK3y: \ --data-urlencode "query=customer.email:'somebody@example.com'" ``` #### Numeric filter Filter payments with a `amount` greater than `1000` in cents.' ```shell curl -G https://api.ophelos.com/payments \ -u sk_prod_H4x0rN0t4R3alAPiK3y: \ --data-urlencode "query=amount>1000" ``` #### Combining multiple filters Lookup debts updated on or after 1st July 2024 and a `status` of `paid`. ```shell curl -G https://api.ophelos.com/debts \ -u sk_prod_H4x0rN0t4R3alAPiK3y: \ --data-urlencode "query=updated_at>=2024-07-01 AND status:paid" ``` ## Search query language ### Query structure and terminology A query `clause` consists of a `field` followed by an `operator` followed by a `value`: ||| |---|---| | clause | `email="somebody@example.com"` | | field | `email` | | operator | `=` | | value | `"somebody@example.com"` | You can combine multiple query clauses in a search by either separating them with a space, or using the `AND` or `OR` keywords (case-insensitive). You can't combine `AND` and `OR` in the same query. Furthermore, there's no option to use parentheses to give priority to certain logic operators. By default, the API combines clauses with `AND` logic. The example query `email:"somebody@example.com" metadata["key"]:"value"` matches records where both the email address is `somebody@example.com`, and the metadata in the record includes `key` with a value of `value`. ## Supported query fields for each resource ### Query fields for customers | Field | Usage | Type | | ----- | ----- | ---- | | `email` | `email=somebody@example.com` | string | | `phone` | `phone=+447500000000` | string | | `mobile` | `mobile=+447500000000` | string | | `country_code` | `country_code=GB` | string | | `postal_code` | `postal_code=FA5 3KE` | string | | `updated_at` | `updated_at>=2024-07-01` | string | | `organisation_id` | `organisation_id=org_Z7Aa5X` | string | | `metadata` | `metadata["key"]:"value"` | token | ### Query fields for debts | Field | Usage | Type | | ----- | ----- | ---- | | `status` | `status:"paying"` | string | | `account_number` | `account_number="A-1234567890"` | string | | `reference_code` | `reference_code="a1b2c3"` | string | | `updated_at` | `updated_at>=2024-07-01` | string | | `created_at` | `created_at=2024-07` | string | | `organisation_id` | `organisation_id=org_Z7Aa5X` | string | | `metadata` | `metadata["key"]:"value"` | token | ### Query fields for Payments | Field | Usage | Type | | ----- | ----- | ---- | | `status` | `status:"succeeded"` | string | | `updated_at` | `updated_at>=2024-07-01` | string | | `created_at` | `created_at=2024-07` | string | | `payment_provider` | `payment_provider:Stripe` | string | | `organisation_id` | `organisation_id=org_Z7Aa5X` | string | | `metadata` | `metadata["key"]:"value"` | token | ### Query fields for Invoices | Field | Usage | Type | | ----- | ----- | ---- | | `status` | `status=paid` | string | | `reference` | `reference:"2-2"` | string | | `description` | `description:"item 4"` | string | # Changelog All notable changes to this project will be documented here. The Changelog format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Calendar Versioning](https://calver.org/). ## [20240701] - 2024-09-12 ### Changed - Converted from RAML to OpenAPI 3.1 - Debt Status to expand with more context of the status when and why ### Removed - `*.external_id` from all resources - `payment.scheduled_at` - `payment.debt` nested object use `debt_id` instead - [BREAKING CHANGE] Auto expanded payloads from the API, use `expand` query parameter instead. ([Learn More](/#section/Expanding-Responses)) - `line_item._destroy` we do not offer the support for deleting line items, erroneous data should be corrected with a new line item. ### Added - A series of new debt webhook events. - Endpoints to create, view, and manage, Debts, Customers, Payments, Line Items, Payment Plans and Organisations - `payment.organisation_id` - Expandable Endpoints - Payment Endpoint & Example Guides for Retrieving Payments - Fixed IP Addresses for Production and Staging - Pagination Headers - Debt originator requirement for purchased debts - Search API for Customers, Debts, and Payments ## [2.1.6] - 2024-05-08 ### Added - `debt.kind` marks a debt as `purcahsed` PI/PD or `managed` for CMS ### Changed - `customer.full_name` to optional - `customer.first_name` to optional - `customer.last_name` to optional ## [2.1.5] - 2024-04-09 ### Added - `debt.resumed` event - after a debt transitions from suspended, the resumed event will be emitted. - Min/Max lengths to all strings ### Fixed - `debt.suspended` metadata useful for identifying the debt records was missing from the payload entirely. ## [2.1.4] - 2024-04-09 ### Changed - `outbound.status` to string ## [2.1.3] - 2024-03-21 ### Added - `support_agent` to `customer_contact_details.source` ## [2.1.2] - 2024-03-15 ### Changed - `payment_plan.next_payment_on` to `date` from `datetime` type - `payment_plan.start_on` to `date` from `datetime` type. - `payment.payment_provider` to optional for scheduled payments. - `payment.transaction_ref` to optional for scheduled payments ### Breaking change - `payment_plan.next_payment_at` to `payment_plan.next_payment_on` ## [2.1.1] - 2024-03-07 ### Changed - `customer_contact_details.usage` field `primary` becomes `permanent` - Note: `usage`, `status` and `source` will have additional enums in the future. ### Removed - `payment.scheduled_at` deprecated ## [2.1.0] - 2024-02-26 ### Added - `customer_contact_details.external_id` ### Changed - make `invoice.remaining_amount` optional - make `invoice.paid_amount` optional - make `invoice.external_id` optional - make `payment_plan.start_on` optional - make `payment_plan.activated_at` optional ## [2.0.3] - 2024-01-30 ### Changed - make `debt.amount` optional as it's deprecated, use `debt.total_amount` ### Removed - remove `*.metadata.cff1_raw_source` as the field is too long to process for some services ## [2.0.2] - 2024-01-23 ### Added - IP Whitelist documentation - `customer.date_of_birth` - `customer.preferred_locale` ### Changed - `debt.start_at` type to date from datetime - `*.external_id` all external ID's are optional for internal created records. - `line_item.transaction_at` made optional - `*.metadata.cff1_raw_source` is a newline separated string, not an array. ### Deprecated - `organisation.vat_number` - `debt.amount` - use `debt.total_amount` instead - `*.metadata.cff1_raw_source` - soon to be deprecated if the field remains unused ## [2.0.1] - 2024-01-09 ### Added - Webhook Event previous attribute examples - Webhook Event ID - `*.refresh` event types as actions to request the most up-to-date information - `Invoice` data type that belongs to debt and can have many `LineItem` and `Payment` associations. - `CollectionAgent` to webhook events - `Organisation` to webhook events - `ContactDetail` the details that are used to contact a customer - `CustomerContactDetail` the association between `ContactDetail` and `Customer`. - `external_id` to Customer, Debt, Organisation and Collection Agent. - metadata to `Customer` ### Changed - `Outbound` contact changes to `CustomerDetail` to clearly signal the exact contact detail used. ### Removed - Debt status `hold` - this status is not officially represented in our debt. Use `suspended_at` and `suspended_until` to understand if a debt is in a state of hold. - `Customer` attributes for `email`, `phone`, `mobile`, and `address`. We're representing customer contact details in `ContactDetail` model. - `Contact` model, use `CustomerContactDetail` and `ContactDetail` models instead. - `Address`, `Email`, `TelephoneNumber` datatypes, use `ContactDetail` model instead. - `Customer` `preferred_contact`. Theres no current support for preferred contact detail. ## [2.0.0-alpha.8] - 2023-12-19 ### Changed - F.A.Q for Webhook Event Types. ## [2.0.0-alpha.7] - 2023-12-18 ### Added - F.A.Q to Webhook Event Types documentation. ## [2.0.0-alpha.6] - 2023-12-14 ### Added - Webhook Example for Closed Debt event - Metadata including RAW source data - Metadata including Intrum representaive ID's ## [2.0.0-alpha.5] - 2023-12-06 ### Added - Webhook Security Documentation - Collection Agency datatype - Organisation has reference to Collection Agency ## [2.0.0-alpha.4] - 2023-12-05 ### Changed - Extracted documentation into a Git Submodule ### Added - Authorization Bearer Token Security Scheme - Reference CFF1 documents for Organisation, Debts, Line Item, Payments, Outbound, and Customer ## [2.0.0-alpha.3] - 2023-11-14 ### Added - This CHANGELOG - Add Outbound type to Resource Types - Add Finished Payment Plan example ## [2.0.0-alpha.2] - 2023-11-13 ### Added - Object type for Address, Email and TelephoneNumber DataTypes - Organisation DataType - Example Debt object parent for Contact - Organisation object parent for Debt ### Changed - Refactored the Contact details examples - Changed the accepted enum types for Payment ### Fixed - Corrected RAML shebang DataType for Telephone Number, and Address ### Removed - Removed `payment_plan` from Debt object ## [2.0.0-alpha.1] - 2023-11-10 ### Added - Outbound DataType for outbound communications to customers ### Updated - Updated the implemented Webhook Events in table