# RAAL Customer Portal — External API | Raal Help Center

> RAAL Customer Portal — External API — Raal help center.

Source: https://raal.io/help/api-documentation/raal-customer-portal-external-api

---

API documentation

# RAAL Customer Portal — External API

5 min read Updated 3 August 2026

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:** `CompanyEmployee`**Response 200:** `CompanyEmployee`

* * *

#### POST `/external/company/employee`

Add a new employee.

|  |  |  | ParamInRequiredType |
| --- | --- | --- | --- |
| email | query | yes | string |

**Request body:** `CompanyUser`**Response 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:** `CreateOrderRequest`**Response 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 |

* * *

On this page

-   [Authentication](#bb34zlxiyc3)
-   [Endpoints](#ypy3zk316rk)
-   [Company](#ypldpy16sal)
-   [Orders (ext-order-controller)](#dceb8xk8sms)
-   [Data Models](#fx3ekyyc5kc)