Send Requests

Use these guidelines when sending requests using the BRM REST Services Manager API.

URL Structure

Here's the URL structure for the requests:

https://hostname:port/brm/apiType/version/resourcePath

where:

  • hostname is the host name of the BRM REST Services Manager server.

  • port is the port for the BRM REST Services Manager server.

  • apiType and version are the type and version of the API:

    • For the Account Management API, use accountManagement/v5.

    • For the Customer Bill Management API, use customerBillManagement/v4.

    • For the Payment Management API, use payment/v4.

    • For the Payment Method Management API, use paymentMethods/v4. The Payment Method API supports versions v1 and v4. Version v4 is the newer version.

    • For the Prepay Balance Management API, use prepayBalanceManagement/v4.

    • For the Product Inventory Management API, use productInventory/v5.

    • For the Usage Management API, use usageManagement/v4.

  • resourcePath is the path to the endpoint.
For example, the URL for generating a bill on demand is: 
https://hostname:port/brm/customerBillManagement/v4/customerBillOnDemand

Payment Method API Versions and Supported Types

The Payment Method API supports versions v1 and v4. Version v4 is the newer version.

For version v4, the core payment method types are Cash, Check, Bank Account Debit, Bank Card, and Tokenized Card.

BRM SDK also supports the extended payment method types SEPA and Invoice.

URL Structure for Extended REST Framework

If you want to use extended REST Services Manager framework, include the @type query parameter in the URL request:
https://hostname:port/brm/apiType/version/resourcePath?@type=baseObjectOracle

where baseObject is the name of the BRM object, such as CustomerBill, Usage, AccumulatedBalance, or BillingAccount.

For example, the URL for payments is:

https://hostname:port/brm/payment/v4/payment?@type=PaymentOracle

For more information, see "Extend the BRM REST Services Manager Framework".

Supported Methods

You can create, retrieve, update, and delete resources using standard HTTP/HTTPS method requests, as summarized in the following table:

HTTP Method Description
GET Retrieve information about the resource.
POST Create the resource.
PATCH Partially update the resource.
DELETE Delete the resource.

Media Types

The BRM REST Services Manager API supports the following media types:

  • application/json
  • (Customer Bills/Invoices Only) application/pdf

Supported Headers

The BRM REST Services Manager API supports the following headers that can be included in the HTTP request or response:

Header Description Example
Content-Type Media type of the body of the request. Required for POST and PATCH requests. Content-Type: application/json
X-ID-TENANT-NAME Identity domain name of BRM REST Services Manager, used for authentication. X-ID-TENANT-NAME:ExampleIdentityDomain

Common Query Parameters

You can use the following common query parameters to limit the results returned by BRM REST Services Manager GET requests:

  • offset: The number of results to offset the response by. Used in GET requests that return a list of results.
  • limit: The maximum number of results to return. Used in GET requests that return a list of results.
  • fields: The properties to show values for in the response. Used in all GET requests. The possible values for this parameter depend on the resource being requested. All properties of the resource will still appear in the response, but their values will be null. Depending on the endpoint, values for some required properties, such as IDs, will appear regardless of this parameter.

  • fieldname.like: The URL-encoded wild card character %25 replaces one or more digits in a string. For example, to search for a string with the prefix B1-706, enter B1-706%25. Used in GET requests.

    If the string includes an actual percent character (%), use the URL-encoded backslash as an escape. For example, to search for a string with the prefix B1%, enter B1%5C%25-3.

For example, a cURL request submitted to the Get Payments endpoint using all three of the above query parameters would look like this:

curl -X GET 'http://host:port/brm/payment/v4/payment?limit=5&offset=10&fields=paymentDate,account'

If there were more than 14 payments recorded in the system, the response would include payments 1 through 14 and show values for the paymentDate and account fields.

Note:

If you submit a request to a multischema BRM system, the response includes results from each schema. In the example above, in a two-schema system, the response would include five results from the first schema followed by five from the second schema. The schema is indicated in the first four digits of an object's ID: 0.0.0.1+-item-payment+84530 or 0.0.0.2+-item-payment+84530.