> ## Documentation Index
> Fetch the complete documentation index at: https://docs.einvoice.sa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboard a Device

## What it does

Registers a new device/organization for e-invoicing before you can clear or report any documents. This is required once per device before you can call any invoice, credit note, or debit note endpoint.

## Authentication

Requires a valid token from [Authenticate](/api-reference/auth/authenticate).

## Request Body

<ParamField body="otp" type="string" required>
  One-time password sent for verification
</ParamField>

<ParamField body="vat_number" type="string" required>
  Your organization's 15-digit VAT number
</ParamField>

<ParamField body="device_id" type="string" required>
  Unique identifier you choose for this device
</ParamField>

<ParamField body="invoice_type" type="string" required>
  `standard`, `simplified`, or `both` — see note below
</ParamField>

<ParamField body="org_name" type="string" required>
  Legal business name
</ParamField>

<ParamField body="org_unit" type="string" required>
  Branch or unit name (e.g. city/location)
</ParamField>

<ParamField body="business_category" type="string" required>
  Industry category, e.g. `IT`, `Retail`
</ParamField>

<ParamField body="registered_address" type="string" required>
  Registered business address
</ParamField>

<ParamField body="country_code" type="string" required>
  ISO country code, e.g. `SA`
</ParamField>

<ParamField body="email_id" type="string" required>
  Contact email for this onboarding
</ParamField>

<Info>
  **Choosing `invoice_type`:**

  * `standard` — for B2B invoices requiring real-time clearance
  * `simplified` — for B2C invoices, reported (not cleared) within 24 hours
  * `both` — device can issue either type
</Info>

## Example Request

```bash theme={null}
curl -X POST https://api.einvoice.sa.com:9090/v1/e-invoicing/onboardings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "otp": "464316",
    "vat_number": "311262046600003",
    "device_id": "SIMAHUATONBOARDTESTING",
    "invoice_type": "both",
    "org_name": "Goagile Technologies",
    "org_unit": "Riyadh",
    "business_category": "IT",
    "registered_address": "Al-Morabba",
    "country_code": "SA",
    "email_id": "support@goagile.com"
  }'
```

## Example Response

```json theme={null}
{
  "onboard_id": "NjU5YTcyYTI2NGE4MmI5ZjNmMDY2NjY5OjMxMTI2MjA0NjYwMDAwMzpEZXZpY2VJZC0wMDE=",
  "status": "success"
}
```

<Warning>
  Save the `onboard_id` returned here — every invoice, credit note, and debit note endpoint requires it in the URL path.
</Warning>

## Where to get the OTP

## Errors

| Code | Meaning                       |
| ---- | ----------------------------- |
| 400  | Invalid or expired OTP        |
| 409  | Device already onboarded      |
| 401  | Missing or invalid auth token |