How does the authentication work?

An API user account is required to access the APIs - this can be setup on Elevate in the manage users/roles sections. Elevate API uses Bearer authentication (also called token authentication) - this is an HTTP authentication scheme that uses security tokens called bearer tokens.

How does the authorisation work?

The permissions set up on Elevate UI will stand for the API calls as well. For example, if a user can only access customers belonging to a single contract owner on the UI, that user will have the same restriction when calling via the APIs.

How to use pagination?

When using GET methods, the page and pageSize query parameters are required to set which page is returned and the maximum number of results per page. For example, GET /customers?page=1&pageSize=10 returns the first 10 records. The maximum pageSize supported is 1000 for performance reasons.

How to set up a billing customer

Almost all scenarios start by creating a Customer with a Site using the POST /customers endpoint. If there are additional sites, you can use POST /sites to create them.

Next, the products and services sold to this customer would be added as inventory items using the POST /usage-product-inventories endpoint to create Usage Product Inventories and the POST /rental-product-inventories endpoint to create Rental Product Inventories.

Within Usage Product Inventories, there can be one or more usage product references. These could be a telephone number or other identifier depending on the Usage Product. When creating a Usage Product Inventory, you can specify these as a list. To add additional usage product references, you can use the add operation on PATCH /usage-product-inventories endpoint. Read more on JSON patching.

The next step is to assign Usage and Rental Rate Cards which are necessary to make sure the customer will be billed accordingly. Usually, these are done by the POST /usage-rate-card-assignments and POST /rental-rate-card-assignments endpoints.

At this stage, you should have enough set up for the customer to produce a bill on Elevate.

How to update an individual usage product reference?

Within Usage Product Inventories, there can be one or more usage product references. Where you need to update an individual usage product reference, you can use the add or replace operation on the PATCH /usage-product-references endpoint. Read more on JSON patching.

200

OK. The request has succeeded.

201

Created. The request has been accepted and resulted in a new resource being created. The newly created resource will be returned with a unique ID

204

No Content. The request was successful, but no body was returned.

400

Bad Request. The request could not be processed by the server, usually due to malformed syntax or server error. The response body will contain error details.

401

Unauthorized. The client has not provided a valid Authentication information or the user account making the request has been disabled. The response body will contain error details

403

Forbidden. The client has provided valid Authentication information, but does not have sufficient permission to access this resource.

404

Not Found. The requested resource was not found. The response body will contain error details.

405

Not Allowed.

406

Not Acceptable. The content type specified was not acceptable.

409

Conflict. The resource requested to be created already exists.

415

Unsupported Media/MIME Type.

500

Internal Server Error. The server encountered an error while processing your request and failed. Please contact Elevate support.

29/09/2022

• New endpoint POST /sim-modification-request added to the Provisioning REST API to allow provisioning changes on SIM products (such as smart barring/suspending etc.)
• New endpoint GET /provisioning-details added to the Inventory REST API to get a list of provisioning details for existing rental product inventories
• Extended POST /invoice-payment-events end point on the Invoices REST API to allow undoing a payment on invoices
• New endpoint POST /sim-subscription-request added to the Provisioning REST API to allow data bundle subscriptions on SIM products
• New endpoint POST /sim-activation-request on the Provisioning REST API
• New endpoint POST /sim-suspension-request on the Provisioning REST API
• New filter parameter generatedInvoiceId added to GET /invoice-payments end point on the Payments REST API
• New filter parameter generatedAdhocInvoiceId added to GET /adhoc-invoice-payments end point on the Payments REST API

15/06/2022

• PATCH /customers REST API has been enhanced with an optional new property customerContacts to represent contacts at customer level
• POST /admin-contacts REST API has been added to allow creation of admin-level contacts

26/04/2022

• New end point /customer-usage-data added to the Customers REST API to get usage records (i.e. rated CDRs) for a given customer
• New end point /users has been added to the Authentication REST API to create/get/edit Elevate users along with another read only end point /user-roles
• PATCH /customers REST API has been enhanced to allow cascading an end date to all inventories when end dating a customer or a site (an additional header parameter cascade_end_date should be passed in along with the endDate)
• New end point DEL /customer-contracts added to the Contracts REST API to allow deleting unused customer contracts
• New property paymentTermsInDays added to customers.sites.siteInvoiceDetails object under customers end point to specify payment collection day of the month for automatic direct debit collections such as GoCardless or Finastra

24/02/2022

• Adhoc inventories API extended to include the billRunId and adhocBillRunId
• Invoices API extended to include totalRentalAmount, totalRentalTaxAmount, totalUsageAmount, totalUsageTaxAmount, totalAdhocAmount, totalAdhocTaxAmount, totalBoltOnAmount, totalBoltOnTaxAmount and totalReverseVatAmount.

10/01/2022

• New endpoints HEAD /usage-rate-cards has been added to the pricing API to check usage cards exist based on filter criteria
• New endpoints HEAD /rental-rate-cards has been added to the pricing API to check rental cards exist based on filter criteria
• New endpoints POST/PATCH /usage-rate-cards has been added to pricing API to add and edit usage rate cards
• New endpoints POST/PATCH /rental-rate-cards has been added to pricing API to add and edit rental rate cards
• New end points DEL/PATCH /usage-rates has been added to pricing API to remove/update rates in usage rate cards
• New end points DEL/PATCH /rental-rates has been added to pricing API to remove/update rates in rental rate cards

06/09/2021

• Added new endpoints for managing contract profiles and customer/RPI contract assignment
• New endpoint GET /email-status to return the status of email notifications sent from Elevate using the AWS email distribution service

25/08/2021

• New endpoint POST /resend-invoice has been added to invoices API to send a copy of the customer invoice email to configured contacts
• New endpoint GET /invoice-summaries has been added to invoices API to retrieve the invoice summary PDF document
• New endpoint POST /invoice-payment-reprocess has been added to payments API to reprocess integrated payment for failed/skipped ones

17/05/2021

• Rental product, usage product, and rental product inventory APIs extended to include any custom fields they may have been configured with
• New endpoint GET /rental-etcs has been added to a new rental rating end point to allow retrieval of early termination charges (ETCs) for a given contracted rental product inventory or customer

01/04/2021

• New endpoint GET /customer-billing-summaries has been added to the customer API to allow retrieval of bill values and rating status of customers in the open bill run and the previous (closed) bill run

04/03/2021

• The version of the Inventory and Products endpoints has been incremented: these endpoints are now on /v2/; e.g. /v2/usage-product-inventories, /v2/usage-products.
• On v2/usage-product-inventories: mainBillingNumber renamed to primary
• On v2/rental-product-inventories: mainBillingNumber renamed to productReference
• On v2/rental-product-inventories: serviceId renamed to additionalProductReference
• On v2/rental-product: serviceIdRequired renamed to additionalProductReferenceRequired
• On v2/rental-product: billingNumberRequired renamed to productReferenceRequired
• On v2/rental-product: moreThanOneBillingNumberRequired renamed to moreThanOneProductReference
• On v2/rental-product: billingNumberMayBeDDIRange renamed to productReferenceMayBeDDIRange

28/01/2021

• The version of the pricing endpoints has been incremented. These are now on /v2/; e.g. /v2/rental-rate-cards. All other end points are still served on /v1
• On /rental-rate-cards and /usage-rate-cards, the contractOwnerId field (previously an int32) has been replaced by an array object of int32 values. This property is called contractOwnerIds

19/01/2021

• New end points added into the payments API: /invoice-payments; /adhoc-invoice-payments; /customer-payments; customer-balances

23/12/2020

• New /bill-runs end point added to manage bill runs API
• Minor bug fixes and missing validations added

06/11/2020

• New /usage-product-references PATCH API added to simplify product reference (UPR) updates
• Fixed an issue to allow no supplier account for usage product inventories

19/10/2020

• New end point added to the invoice API to get the invoice in pdf format
• Fixed an issue prevented patching customers

28/08/2020

• Added new end point for Payments and refunds
• Invoices API has additional read only properties: refund status and refund status updated date (both can be used as filters)

23/08/2020

• Added new end point for invoices
• Customers end point has additional read only properties: created date, updated date, mandate created date, mandate updated date and mandate status (all can be used as filters)

26/03/2020

• Release 1.0 of the Elevate REST API
• Authentication, customer, site and relevant reference data apis included