API documentation

RAAL Customer Portal — External API

13 min read Updated 22 October 2026

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

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

Authentication

Every request requires both of the following:

Scheme

Type

Where

Details

ApiKey

API key

Header Authorization

Company API key. The prefix depends on the environment, for example raal-live-abc123 in production. If you cannot set the header, pass the key as the api_key query parameter instead.

EmailHeader

API key

Header email

Email address of the acting employee

Note: almost every endpoint also requires email as a query parameter. Check the parameter table per endpoint.

Company

Subscription, settings, ops, employees and billing for your company.

GET /external/company/subscription

Get the company's current subscription.

Param

In

Required

Type

email

query

yes

string

currency

query

no

string

Response 200: SubscriptionResponse

PUT /external/company/subscription

Create or change the company's subscription (tier, billing period, ops amount). When payment is needed, the response includes Stripe payment details (clientSecret, hostedInvoiceUrl, stripeInvoiceId) and an outcome.

Param

In

Required

Type

email

query

yes

string

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

Response 200: SubscriptionResponse

GET /external/company/subscription/preview

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

Param

In

Required

Type

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

DELETE /external/company/subscription/pending

Cancel a scheduled subscription change that has not taken effect yet.

Param

In

Required

Type

email

query

yes

string

Response 200: SubscriptionResponse

PUT /external/company/settings

Update company settings.

Param

In

Required

Type

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.

Param

In

Required

Type

email

query

yes

string

Response 200: CompanyOpsPolicyDto

PUT /external/company/ops-policy

Set the company's ops policy.

Param

In

Required

Type

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.

Param

In

Required

Type

email

query

yes

string

Response 200: CompanyOpsPolicyDto

GET /external/company/ops

Get the company's current ops balance / usage.

Param

In

Required

Type

email

query

yes

string

Response 200: OpsResponse

GET /external/company/ops/consumption-rules

List the ops consumption rules that apply to this company.

Param

In

Required

Type

email

query

yes

string

Response 200: array of OpsConsumptionRuleDto

GET /external/company/employee

Get a single employee by email.

Param

In

Required

Type

email

query

yes

string

Response 200: CompanyEmployee

GET /external/company/employee/all

List all employees for the company.

Param

In

Required

Type

email

query

yes

string

Response 200: array of CompanyEmployee

POST /external/company/employee

Add a new employee.

Param

In

Required

Type

email

query

yes

string

Request body: CompanyUser

Response 200: CompanyEmployee

PUT /external/company/employee

Update an employee.

Param

In

Required

Type

email

query

yes

string

Request body: CompanyEmployee

Response 200: CompanyEmployee

PUT /external/company/employee/{employeeId}/groups

Replace the groups (roles) assigned to an employee.

Param

In

Required

Type

employeeId

path

yes

integer (int64)

email

query

yes

string

Request body: EmployeeGroupsUpdate

Response 200: CompanyEmployee

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

Deactivate an employee.

Param

In

Required

Type

employeeId

path

yes

integer (int64)

email

query

yes

string

Response 200: CompanyEmployee

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

Reactivate a previously deactivated employee.

Param

In

Required

Type

employeeId

path

yes

integer (int64)

email

query

yes

string

Response 200: CompanyEmployee

DELETE /external/company/employee/{employeeId}

Delete an employee.

Param

In

Required

Type

employeeId

path

yes

integer (int64)

email

query

yes

string

Response 200: —

GET /external/company/hr/employees

List employees as sourced from the connected HR system.

Param

In

Required

Type

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.

Param

In

Required

Type

email

query

yes

string

Response 200: string (URL)

GET /external/company/billing-information

Get the company's billing information.

Param

In

Required

Type

email

query

yes

string

Response 200: string

Pricing

Get a price for an order before you create it.

POST /external/price/order

Calculate the price of an order before creating it. Returns the priced order lines.

Param

In

Required

Type

email

query

yes

string

Request body: PriceCalculationRequest

Response 200: array of OrderLine

Orders

Create orders and follow their status, payments and documents.

GET /external/order

List orders for the company.

Param

In

Required

Type

email

query

yes

string

Response 200: array of Order

POST /external/order

Create a new order.

Param

In

Required

Type

email

query

yes

string

Request body: CreateOrderRequest

Response 200: Order

GET /external/order/{orderId}

Get a single order by ID.

Param

In

Required

Type

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.

Param

In

Required

Type

orderId

path

yes

integer (int64)

email

query

yes

string

Response 200: Order

GET /external/order/{orderId}/tax

Get the tax amount for the order.

Param

In

Required

Type

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.

Param

In

Required

Type

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.

Param

In

Required

Type

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.

Param

In

Required

Type

orderId

path

yes

integer (int64)

email

query

yes

string

Response 200: array of OrderChange

GET /external/order/{orderId}/attachments

List attachments on the order.

Param

In

Required

Type

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.

Param

In

Required

Type

orderId

path

yes

integer (int64)

attachmentId

path

yes

integer (int64)

email

query

yes

string

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

Assets

Keep track of your company's devices: holders, condition, security, finance and history.

GET /external/asset

List the company's assets. Returns a paged result.

Param

In

Required

Type

email

query

yes

string

Response 200: AssetPageDto

POST /external/asset

Create a new asset.

Param

In

Required

Type

email

query

yes

string

Request body: AssetCreateRequest

Response 200: AssetDto

GET /external/asset/{id}

Get a single asset by ID, with all fields.

Param

In

Required

Type

id

path

yes

integer (int64)

email

query

yes

string

Response 200: AssetDto

PATCH /external/asset/{id}

Update an asset. Send only the fields you want to change.

Param

In

Required

Type

id

path

yes

integer (int64)

email

query

yes

string

Request body: AssetUpdateRequest

Response 200: AssetDto

DELETE /external/asset/{id}

Delete an asset.

Param

In

Required

Type

id

path

yes

integer (int64)

email

query

yes

string

Response 200: —

POST /external/asset/{id}/audit

Record an audit of the asset and set its audit status.

Param

In

Required

Type

id

path

yes

integer (int64)

email

query

yes

string

Request body: AssetAuditRequest

Response 200: AssetDto

GET /external/asset/{id}/history

Get the change history of an asset, newest first. Paginated.

Param

In

Required

Type

id

path

yes

integer (int64)

email

query

yes

string

page

query

no

integer (int32), default 0

pageSize

query

no

integer (int32), default 20

Response 200: array of AssetHistoryDto

GET /external/asset/{id}/attachments

List the attachments on an asset.

Param

In

Required

Type

id

path

yes

integer (int64)

email

query

yes

string

Response 200: array of AssetAttachmentDto

POST /external/asset/{id}/attachments

Upload an attachment to an asset (multipart/form-data).

Param

In

Required

Type

id

path

yes

integer (int64)

Request body: multipart/form-data, file

Response 200: AssetAttachmentDto

GET /external/asset/{id}/attachments/{attachmentId}

Get a single asset attachment. Returns a URL to view or download the file.

Param

In

Required

Type

id

path

yes

integer (int64)

attachmentId

path

yes

integer (int64)

email

query

yes

string

Response 200: AssetAttachmentImageDto

DELETE /external/asset/{id}/attachments/{attachmentId}

Delete an attachment from an asset.

Param

In

Required

Type

id

path

yes

integer (int64)

attachmentId

path

yes

integer (int64)

email

query

yes

string

Response 200: —

POST /external/asset/import

Create or update assets in bulk. Returns how many rows were created, updated and failed, with an error message per failed row.

Param

In

Required

Type

email

query

yes

string

Request body: AssetImportRequest

Response 200: AssetImportResult

GET /external/asset/export

Export all of the company's assets as a file.

Param

In

Required

Type

email

query

yes

string

Response 200: file download

GET /external/asset/export/finance

Export the company's assets with their finance fields (purchase, insurance, depreciation) as a file.

Param

In

Required

Type

email

query

yes

string

Response 200: file download

Data Models

Objects used in the requests and responses above.

SubscriptionResponse

Field

Type

current

SubscriptionTierDto

tiers

array of SubscriptionTierDto

clientSecret

string

hostedInvoiceUrl

string

stripeInvoiceId

string

outcome

string

pendingActivation

PendingActivation

currentOpsAmount

integer (int32)

currentBillingPeriod

string

currentCurrency

string

nextRenewalDate

string (date)

pendingChange

PendingChange

entitlements

object (map of string → boolean)

limits

object (map of string → integer (int64))

featureCatalog

array of FeatureRequirement

SubscriptionTierDto

Field

Type

id

integer (int64)

name

string

priceMonthly

number

currency

string

contactSales

boolean

billingPeriods

array of BillingPeriodPricing

gates

object (map of string → boolean)

BillingPeriodPricing

Field

Type

period

string

opsVariants

array of OpsVariant

OpsVariant

Field

Type

opsAmount

integer (int32)

stripePriceId

string

price

number

currency

string

annualOpsAmount

integer (int32)

priceAnnual

number

PendingChange

Field

Type

effectiveDate

string (date-time)

tierId

integer (int64)

tierName

string

opsAmount

integer (int32)

billingPeriod

string

PendingActivation

Field

Type

tierId

integer (int64)

tierName

string

opsAmount

integer (int32)

billingPeriod

string

stripeInvoiceId

string

hostedInvoiceUrl

string

invoicePdf

string

amountDue

integer (int64)

currency

string

dueDate

string (date)

FeatureRequirement

Field

Type

key

string

minTierId

integer (int64)

minTierName

string

SubscriptionChangePreviewDto

Field

Type

amountDueCents

integer (int64)

subtotalCents

integer (int64)

taxCents

integer (int64)

currency

string

prorationDate

integer (int64)

lines

array of PreviewLine

reverseCharge

boolean

creditCents

integer (int64)

blockedReason

string

opsGrantedToday

integer (int64)

PreviewLine

Field

Type

description

string

amountCents

integer (int64)

CompanyOpsPolicyDto

Field

Type

policy

string

updatedAt

string (date-time)

pendingPolicy

string

pendingEffectiveDate

string (date)

invoiceOpsCurrencyEnabled

boolean

portalOpsCurrencyEnabled

boolean

OpsResponse

Field

Type

subscriptionAvailable

integer (int64)

topupAvailable

integer (int64)

totalAvailable

integer (int64)

transactions

array (free-form)

OpsConsumptionRuleDto

Field

Type

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

Field

Type

id

integer (int64)

name

string

settings

object (free-form)

invoiceOpsCurrencyEnabled

boolean

portalOpsCurrencyEnabled

boolean

CompanyEmployee

Field

Type

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

viewer

boolean

admin

boolean

CompanyUser

Field

Type

userName

string

userEmail

string

userPassword

string

userActive

boolean

userSettings

object (free-form)

userGroups

array of string

EmployeeGroupsUpdate

Field

Type

groups

array of string

AddressInformation

Field

Type

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

PriceCalculationRequest

Field

Type

collectionInfo

AddressInformation

deliveryInfo

AddressInformation

orderLines

array of PriceCalculationLineRequest

boxExpress

boolean

deviceExpress

boolean

PriceCalculationLineRequest

Field

Type

device

string

quantity

integer (int32)

itemValue

string

hasPackage

boolean

details

object (free-form)

CreateOrderRequest

Field

Type

number

string

collectionInfo

AddressInformation

deliveryInfo

AddressInformation

customerComment

string

internalReference

string

orderLines

array of CreateOrderLineRequest

shipment

object (free-form)

paymentPolicy

string

expectedOpsTotal

integer (int64)

CreateOrderLineRequest

Field

Type

device

string

quantity

integer (int32)

itemValue

string

hasPackage

boolean

deviceSerialNumber

string

deviceManufacturer

string

deviceModel

string

details

object (free-form)

Order

Field

Type

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

Field

Type

device

string

quantity

integer (int32)

unitPrice

number

customsClearance

number

customsCosts

number

itemValue

string

hasPackage

boolean

deviceSerialNumber

string

deviceManufacturer

string

deviceModel

string

assetId

integer (int64)

assetMovement

string

details

object (free-form)

finalUnitPrice

number

finalCustomsCosts

number

finalCustomsClearance

number

OrderChange

Field

Type

created

string (date-time)

description

string

OrderAttachment

Field

Type

id

integer (int64)

orderId

integer (int64)

created

string (date-time)

name

string

content

string

AssetPageDto

Field

Type

content

array of AssetSummaryDto

page

integer (int32)

pageSize

integer (int32)

totalElements

integer (int64)

AssetSummaryDto

Field

Type

id

integer (int64)

companyId

integer (int64)

assetTag

string

serialNumber

string

model

string

manufacturer

string

category

string

status

string

conditionGrade

string

warrantyEnd

string (date)

holderId

integer (int64)

holderName

string

holderBusinessEmail

string

holderPrivateEmail

string

holderPhone

string

locationCountry

string

locationAddress

string

notes

string

enrolledInMdm

boolean

assignedAt

string (date)

deviceInUseFrom

string (date)

auditStatus

string

lastAuditedAt

string (date-time)

purchaseDate

string (date)

disposalDate

string (date)

endOfLifeDate

string (date)

created

string (date-time)

updated

string (date-time)

AssetDto

Field

Type

id

integer (int64)

companyId

integer (int64)

assetTag

string

serialNumber

string

model

string

manufacturer

string

category

string

status

string

warrantyStart

string (date)

warrantyEnd

string (date)

warrantyProvider

string

holderId

integer (int64)

holderName

string

holderBusinessEmail

string

holderPrivateEmail

string

holderPhone

string

locationCountry

string

locationAddress

string

notes

string

conditionGrade

string

conditionNotes

string

functionalNotes

string

conditionScore

integer (int32)

batteryHealth

integer (int32)

batteryCycles

integer (int32)

ramGb

integer (int32)

diskGb

integer (int32)

enrolledInMdm

boolean

assignedAt

string (date)

assignedAtSource

string

deviceInUseFrom

string (date)

auditStatus

string

lastAuditedAt

string (date-time)

lastAuditedById

integer (int64)

encryptionEnabled

boolean

encryptionMethod

string

encryptionKeyEscrowed

boolean

edrInstalled

boolean

edrProduct

string

osName

string

osVersion

string

mdmPlatform

string

mdmComplianceStatus

string

mdmLastCheckIn

string (date)

screenLockEnforced

boolean

department

string

ownershipType

string

assignedByEmployeeId

integer (int64)

dataClassification

string

disposalDate

string (date)

disposalMethod

string

dataDestructionCertRef

string

dataDestructionDate

string (date)

destructionPerformedBy

string

disposalVendor

string

acceptableUseAcceptedAt

string (date)

acceptableUseRef

string

returnedAt

string (date)

incidentRef

string

purchaseDate

string (date)

purchaseCost

number

purchaseCurrency

string

supplier

string

poReference

string

endOfLifeDate

string (date)

insuredValue

number

insurancePolicyRef

string

usefulLifeYears

integer (int32)

currentDepreciatedValue

number

effectiveUsefulLifeYears

integer (int32)

hostname

string

macAddress

string

imei

string

physicalAssetTag

string

source

string

created

string (date-time)

updated

string (date-time)

createdBy

integer (int64)

updatedBy

integer (int64)

AssetCreateRequest

Field

Type

assetTag

string

serialNumber

string

model

string

manufacturer

string

category

string

status

string

warrantyStart

string (date)

warrantyEnd

string (date)

warrantyProvider

string

holderName

string

holderBusinessEmail

string

holderPrivateEmail

string

holderPhone

string

locationCountry

string

locationAddress

string

notes

string

conditionGrade

string

conditionNotes

string

functionalNotes

string

conditionScore

integer (int32)

batteryHealth

integer (int32)

batteryCycles

integer (int32)

ramGb

integer (int32)

diskGb

integer (int32)

enrolledInMdm

boolean

assignedAt

string (date)

deviceInUseFrom

string (date)

encryptionEnabled

boolean

encryptionMethod

string

encryptionKeyEscrowed

boolean

edrInstalled

boolean

edrProduct

string

osName

string

osVersion

string

mdmPlatform

string

mdmComplianceStatus

string

mdmLastCheckIn

string (date)

screenLockEnforced

boolean

department

string

ownershipType

string

assignedByEmployeeId

integer (int64)

dataClassification

string

disposalDate

string (date)

disposalMethod

string

dataDestructionCertRef

string

dataDestructionDate

string (date)

destructionPerformedBy

string

disposalVendor

string

acceptableUseAcceptedAt

string (date)

acceptableUseRef

string

returnedAt

string (date)

incidentRef

string

purchaseDate

string (date)

purchaseCost

number

purchaseCurrency

string

supplier

string

poReference

string

endOfLifeDate

string (date)

insuredValue

number

insurancePolicyRef

string

usefulLifeYears

integer (int32)

hostname

string

macAddress

string

imei

string

physicalAssetTag

string

source

string

AssetUpdateRequest

Field

Type

updated

string (date-time)

serialNumber

string

model

string

manufacturer

string

category

string

status

string

warrantyStart

string (date)

warrantyEnd

string (date)

warrantyProvider

string

holderName

string

holderBusinessEmail

string

holderPrivateEmail

string

holderPhone

string

locationCountry

string

locationAddress

string

notes

string

conditionGrade

string

conditionNotes

string

functionalNotes

string

conditionScore

integer (int32)

batteryHealth

integer (int32)

batteryCycles

integer (int32)

ramGb

integer (int32)

diskGb

integer (int32)

enrolledInMdm

boolean

assignedAt

string (date)

deviceInUseFrom

string (date)

encryptionEnabled

boolean

encryptionMethod

string

encryptionKeyEscrowed

boolean

edrInstalled

boolean

edrProduct

string

osName

string

osVersion

string

mdmPlatform

string

mdmComplianceStatus

string

mdmLastCheckIn

string (date)

screenLockEnforced

boolean

department

string

ownershipType

string

assignedByEmployeeId

integer (int64)

dataClassification

string

disposalDate

string (date)

disposalMethod

string

dataDestructionCertRef

string

dataDestructionDate

string (date)

destructionPerformedBy

string

disposalVendor

string

acceptableUseAcceptedAt

string (date)

acceptableUseRef

string

returnedAt

string (date)

incidentRef

string

purchaseDate

string (date)

purchaseCost

number

purchaseCurrency

string

supplier

string

poReference

string

endOfLifeDate

string (date)

insuredValue

number

insurancePolicyRef

string

usefulLifeYears

integer (int32)

overrideDeviceInUseFrom

boolean

hostname

string

macAddress

string

imei

string

physicalAssetTag

string

AssetAuditRequest

Field

Type

status

string

AssetHistoryDto

Field

Type

id

integer (int64)

assetId

integer (int64)

companyId

integer (int64)

action

string

fieldName

string

value

string

source

string

importBatchId

string

orderId

integer (int64)

editGroupId

string

created

string (date-time)

createdByEmployeeId

integer (int64)

AssetAttachmentDto

Field

Type

id

integer (int64)

assetId

integer (int64)

companyId

integer (int64)

docType

string

fileName

string

fileSize

integer (int64)

mimeType

string

notes

string

created

string (date-time)

updated

string (date-time)

createdByEmployeeId

integer (int64)

updatedByEmployeeId

integer (int64)

AssetAttachmentImageDto

Field

Type

id

integer (int64)

mimeType

string

url

string

AssetImportRequest

Field

Type

rows

array of AssetImportRow

AssetImportRow

Field

Type

serialNumber

string

model

string

manufacturer

string

category

string

status

string

warrantyStart

string

warrantyEnd

string

warrantyProvider

string

holderBusinessEmail

string

holderPrivateEmail

string

holderName

string

holderPhone

string

locationCountry

string

locationAddress

string

notes

string

conditionGrade

string

enrolledInMdm

string

assignedAt

string

deviceInUseFrom

string

AssetImportResult

Field

Type

created

integer (int32)

updated

integer (int32)

failed

integer (int32)

errors

array of AssetImportRowError

AssetImportRowError

Field

Type

rowIndex

integer (int32)

message

string