RAAL Customer Portal — External API

Written By Dainius Figoras

Last updated 15 days ago

Public API for external integrations. Authenticate with your API key and employee email address.

Version: v1 Base URL: http://customerportal-api.raal.io/

Authentication

Every request requires both of the following:

SchemeTypeWhereDetails

ApiKey

API key

Header Authorization

Company API key prefixed with raal-live-. Example: raal-live-abc123

EmailHeader

API key

Header email

Email address of the acting employee

Note: several endpoints below also take email as a query parameter in addition to (or instead of) the header. Check the parameter table per endpoint.

Endpoints

Company

GET /external/company/subscription

Get the company's current subscription.

ParamInRequiredType

email

query

yes

string

currency

query

no

string

Response 200: SubscriptionResponse

GET /external/company/subscription/preview

Preview the cost impact of a subscription change before committing to it.

ParamInRequiredType

email

query

yes

string

tierId

query

yes

integer (int64)

billingPeriod

query

no

string

opsAmount

query

no

integer (int32)

currency

query

no

string

Response 200: SubscriptionChangePreviewDto

GET /external/company/settings

PUT /external/company/settings

Update company settings.

ParamInRequiredType

email

query

yes

string

Request body: application/json, object (free-form) Response 200: object (free-form)

GET /external/company/ops-policy

Get the company's ops (usage) policy.

ParamInRequiredType

email

query

yes

string

Response 200: CompanyOpsPolicyDto

PUT /external/company/ops-policy

Set the company's ops policy.

ParamInRequiredType

email

query

yes

string

Request body: application/json, object (free-form) Response 200: CompanyOpsPolicyDto

DELETE /external/company/ops-policy/pending

Cancel a pending ops-policy change.

ParamInRequiredType

email

query

yes

string

Response 200: CompanyOpsPolicyDto

GET /external/company/ops

Get the company's current ops balance / usage.

ParamInRequiredType

email

query

yes

string

Response 200: OpsResponse

GET /external/company/ops/consumption-rules

List the ops consumption rules that apply to this company.

ParamInRequiredType

email

query

yes

string

Response 200: array of OpsConsumptionRuleDto

GET /external/company/employee

Get a single employee by email.

ParamInRequiredType

email

query

yes

string

Response 200: CompanyEmployee

PUT /external/company/employee

Update an employee.

ParamInRequiredType

email

query

yes

string

Request body: CompanyEmployeeResponse 200: CompanyEmployee

POST /external/company/employee

Add a new employee.

ParamInRequiredType

email

query

yes

string

Request body: CompanyUserResponse 200: CompanyEmployee

GET /external/company/employee/all

List all employees for the company.

ParamInRequiredType

email

query

yes

string

Response 200: array of CompanyEmployee

DELETE /external/company/employee/{employeeId}

Delete an employee.

ParamInRequiredType

employeeId

path

yes

integer (int64)

email

query

yes

string

Response 200: —

POST /external/company/employee/{employeeId}/deactive

Deactivate an employee.

ParamInRequiredType

employeeId

path

yes

integer (int64)

email

query

yes

string

Response 200: CompanyEmployee

POST /external/company/employee/{employeeId}/reactive

Reactivate a previously deactivated employee.

ParamInRequiredType

employeeId

path

yes

integer (int64)

email

query

yes

string

Response 200: CompanyEmployee

GET /external/company/hr/employees

List employees as sourced from the connected HR system.

ParamInRequiredType

email

query

yes

string

Response 200: array of objects (free-form, HR-system-specific)

GET /external/company/billing-portal-link

Get a link to the Stripe billing portal for this company.

ParamInRequiredType

email

query

yes

string

Response 200: string (URL)

GET /external/company/billing-information

Get the company's billing information.

ParamInRequiredType

email

query

yes

string

Response 200: string

Orders (ext-order-controller)

GET /external/order

List orders for the company.

ParamInRequiredType

email

query

yes

string

Response 200: array of Order

POST /external/order

Create a new order.

ParamInRequiredType

email

query

yes

string

Request body: CreateOrderRequestResponse 200: Order

GET /external/order/{orderId}

Get a single order by ID.

ParamInRequiredType

orderId

path

yes

integer (int64)

email

query

yes

string

Response 200: Order

POST /external/order/{orderId}/draft-invoice

Generate a draft invoice for the order.

ParamInRequiredType

orderId

path

yes

integer (int64)

email

query

yes

string

Response 200: Order

GET /external/order/{orderId}/tax

Get the tax amount for the order.

ParamInRequiredType

orderId

path

yes

integer (int64)

email

query

yes

string

Response 200: string

GET /external/order/{orderId}/payment

Get the payment status/details for the order.

ParamInRequiredType

orderId

path

yes

integer (int64)

email

query

yes

string

Response 200: string

GET /external/order/{orderId}/payment-link

Get a payment link (e.g. Stripe checkout) for the order.

ParamInRequiredType

orderId

path

yes

integer (int64)

email

query

yes

string

Response 200: string (URL)

GET /external/order/{orderId}/changes

Get the change history for the order.

ParamInRequiredType

orderId

path

yes

integer (int64)

email

query

yes

string

Response 200: array of OrderChange

GET /external/order/{orderId}/attachments

List attachments on the order.

ParamInRequiredType

orderId

path

yes

integer (int64)

email

query

yes

string

Response 200: array of OrderAttachment

GET /external/order/{orderId}/attachments/{attachmentId}/download

Download a specific attachment.

ParamInRequiredType

orderId

path

yes

integer (int64)

attachmentId

path

yes

integer (int64)

email

query

yes

string

Response 200: byte string (binary content, base64-encoded in JSON)

Data Models

SubscriptionResponse

FieldType

current

SubscriptionTierDto

tiers

array of SubscriptionTierDto

clientSecret

string

currentOpsAmount

integer (int32)

currentBillingPeriod

string

currentCurrency

string

nextRenewalDate

string (date)

pendingChange

PendingChange

SubscriptionTierDto

FieldType

id

integer (int64)

name

string

priceMonthly

number

currency

string

contactSales

boolean

billingPeriods

array of BillingPeriodPricing

BillingPeriodPricing

FieldType

period

string

opsVariants

array of OpsVariant

OpsVariant

FieldType

opsAmount

integer (int32)

stripePriceId

string

price

number

currency

string

annualOpsAmount

integer (int32)

priceAnnual

number

PendingChange

FieldType

effectiveDate

string (date-time)

tierId

integer (int64)

tierName

string

opsAmount

integer (int32)

billingPeriod

string

SubscriptionChangePreviewDto

FieldType

amountDueCents

integer (int64)

subtotalCents

integer (int64)

taxCents

integer (int64)

currency

string

prorationDate

integer (int64)

lines

array of PreviewLine

reverseCharge

boolean

PreviewLine

FieldType

description

string

amountCents

integer (int64)

CompanyOpsPolicyDto

FieldType

policy

string

updatedAt

string (date-time)

pendingPolicy

string

pendingEffectiveDate

string (date)

invoiceOpsCurrencyEnabled

boolean

portalOpsCurrencyEnabled

boolean

OpsResponse

FieldType

subscriptionAvailable

integer (int64)

topupAvailable

integer (int64)

totalAvailable

integer (int64)

transactions

array (free-form)

OpsConsumptionRuleDto

FieldType

operationType

string

opsCost

integer (int64)

consumptionMode

string

description

string

uiVisible

boolean

uiSection

string

uiActionType

string

uiSortOrder

integer (int32)

exclusiveGroup

string

defaultSelected

boolean

consumedWhen

string

Company

FieldType

id

integer (int64)

name

string

settings

object (free-form)

invoiceOpsCurrencyEnabled

boolean

portalOpsCurrencyEnabled

boolean

CompanyEmployee

FieldType

id

integer (int64)

companyId

integer (int64)

email

string

phone

string

name

string

active

boolean

company

Company

settings

object (free-form)

groups

array of string

editor

boolean

admin

boolean

viewer

boolean

CompanyUser

FieldType

userName

string

userEmail

string

userPassword

string

userActive

boolean

userSettings

object (free-form)

userGroups

array of string

AddressInformation

FieldType

firstName

string

lastName

string

email

string

phone

string

address

string

house_number

string

apartment

string

city

string

postal_code

string

country

string

date

string

shipmentType

string

CreateOrderLineRequest

FieldType

device

string

quantity

integer (int32)

itemValue

string

hasPackage

boolean

deviceSerialNumber

string

details

object (free-form)

CreateOrderRequest

FieldType

number

string

collectionInfo

AddressInformation

deliveryInfo

AddressInformation

customerComment

string

internalReference

string

orderLines

array of CreateOrderLineRequest

shipment

object (free-form)

paymentPolicy

string

expectedOpsTotal

integer (int64)

Order

FieldType

id

integer (int64)

companyId

integer (int64)

number

string

created

string (date-time)

updated

string (date-time)

status

enum: NEW, CONFIRMED, BOX_IN_TRANSIT, BOX_RECEIVED, DEVICE_IN_TRANSIT, DELIVERED, COMPLETED, UNDER_CLAIM, CANCELLED, UNREACHABLE, UNDEFINED

employee

CompanyEmployee

collectionInfo

AddressInformation

deliveryInfo

AddressInformation

customerComment

string

internalReference

string

orderLines

array of OrderLine

shipment

object (free-form)

paymentPolicy

string

expectedOpsTotal

integer (int64)

priceAdjustedAt

string (date-time)

OrderLine

FieldType

device

string

quantity

integer (int32)

unitPrice

number

customsClearance

number

customsCosts

number

itemValue

string

hasPackage

boolean

deviceSerialNumber

string

details

object (free-form)

finalUnitPrice

number

finalCustomsCosts

number

finalCustomsClearance

number

OrderChange

FieldType

created

string (date-time)

description

string

OrderAttachment

FieldType

id

integer (int64)

orderId

integer (int64)

created

string (date-time)

name

string

content

string