# KSA v2: Onboard your EGS

Onboard your E-Invoice Generation Solution (EGS) to the ZATCA sandbox with the KSA ZATCA API v2, using your API key and an OTP from the Fatoora portal. This page documents API v2, a legacy version.

> **Legacy API v2**
>
> This page documents API v2, which is no longer developed. New integrations should use the current API: see [Unify](https://docs.complyance.io/api-reference/unify/) and [Saudi Arabia](https://docs.complyance.io/countries/sa/).

After you sign up, sign in and [generate an API key](https://docs.complyance.io/legacy/v2/ksa/api-key-generation/), onboard your E-Invoice Generation Solution (EGS). The onboarding API registers your EGS in the ZATCA sandbox. Send the required parameters in the format shown below. You can add other parameters to fit your needs.

## Add your API key

1. Copy the API key you received when you generated it.
2. Send it in the `x-api-key` header of the onboarding request.

When the request succeeds, you receive a confirmation message such as `EGS EGS-TEST-1234 has been successfully onboarded.`

## Endpoint

```http
POST https://api.complyance.io/sandbox/v2/egsOnboarding
```

## Example request

```json title="Request body"
{
  "csrInputs": {
    "otp": "047307",
    "commonName": "CreditNotes-Sales-Simulation",
    "serialNumber": "1-CreditNotes|2-Sales|3-9c15663c-592c-4593-9888-d3620285fb60",
    "organizationIdentifier": "300000000000003",
    "organizationUnitName": "Jeddah",
    "organizationName": "Acme Trading LLC",
    "countryName": "SA",
    "invoiceType": "1100",
    "location": "Jeddah",
    "industry": "Manufacturing",
    "isB2B": true,
    "isB2C": true,
    "b2BRequirements": {
      "isSelfBilling": false,
      "isThirdParty": false,
      "isSummaryPresent": false,
      "isExport": false,
      "isNominal": false
    },
    "b2CRequirements": {
      "isThirdParty": false,
      "isSummaryPresent": false,
      "isNominal": false
    }
  }
}
```

## Request parameters

| Parameter | Required | Type | Description | Example |
| - | - | - | - | - |
| `csrInputs` | Yes | object | The certificate signing request (CSR) details you provide to onboard the EGS. | See the example request. |
| `otp` | Yes | string | The OTP you get from the Fatoora portal, signed in with the taxpayer’s credentials, after you follow the ZATCA onboarding process. | `123345` |
| `commonName` | Yes | string | A unique name or asset tracking number for your EGS. There is no fixed format: any free text is accepted. | `TST-886431145-300000000000003` |
| `serialNumber` | Yes | string | A unique identification code for the EGS. It must match the regular expression `1-(.+)\|2-(.+)\|3-(.+)`. See the example request for the format. | `1-TST\|2-TST\|3-ed22f1d8-e6a2-1118-9b58-d9a8f11e44yt` |
| `organizationIdentifier` | Yes | string | The organization’s VAT number: a **15**-digit number that starts and ends with **3**. | `300000000000003` |
| `organizationUnitName` | Yes | string | The taxpayer’s branch name. For a VAT group, the 10-digit TIN of the group member whose EGS unit you are onboarding. **If the 11th digit of `organizationIdentifier` is not 1, this is free text. If the 11th digit is 1, it must be a 10-digit number.** | `Riyadh` |
| `organizationName` | Yes | string | The taxpayer’s name. Free text. | `Acme Trading LLC` |
| `countryName` | Yes | string | The country, as a 2-letter code (**ISO 3166 Alpha-2**). | `SA` |
| `invoiceType` | Yes | string | The document types this EGS unit issues: Standard Tax Invoice (T), Simplified Tax Invoice (S), (X) and (Y), written as four digits in the order TSXY. 1 means supported and 0 means not supported. X and Y are reserved for future use and must be 0. For example, `1000` means the EGS issues standard (B2B) invoices only, `0100` means simplified (B2C) invoices only, and `1100` means both. | `1100` |
| `location` | Yes | string | The address of the branch or location where the EGS unit is mainly based. For e-commerce, this can be a website address. The short address format of the [Saudi National Address](https://splonline.com.sa/en/national-address-1/) is preferred but not required. Free text is accepted. | `Riyadh` |
| `industry` | Yes | string | The industry or sector the EGS issues invoices for. Free text. | `Petroleum` |
| `isB2B` | Yes | boolean | Whether the organization makes business-to-business (B2B) transactions. | `true` |
| `isB2C` | Yes | boolean | Whether the organization makes business-to-consumer (B2C) transactions. | `true` |
| `b2BRequirements` | Yes | object | Details about the B2B business. See [B2B requirements](https://docs.complyance.io/legacy/v2/ksa/egs-onboarding/#b2b-requirements). | `{...}` |
| `b2CRequirements` | Yes | object | Details about the B2C business. See [B2C requirements](https://docs.complyance.io/legacy/v2/ksa/egs-onboarding/#b2c-requirements). | `{...}` |

### B2B requirements

| Parameter | Required | Type | Description | Example |
| - | - | - | - | - |
| `isSelfBilling` | Yes | boolean | Whether the organization uses self-billing. | `false` |
| `isThirdParty` | Yes | boolean | Whether third parties are involved in B2B transactions. | `false` |
| `isSummaryPresent` | Yes | boolean | Whether B2B transactions include summary invoices. | `false` |
| `isExport` | Yes | boolean | Whether the organization exports goods to other countries. | `false` |
| `isNominal` | Yes | boolean | Whether B2B transactions use nominal values. | `false` |

### B2C requirements

| Parameter | Required | Type | Description | Example |
| - | - | - | - | - |
| `isThirdParty` | Yes | boolean | Whether third parties are involved in B2C transactions. | `false` |
| `isSummaryPresent` | Yes | boolean | Whether B2C transactions include summary invoices. | `false` |
| `isNominal` | Yes | boolean | Whether B2C transactions use nominal values. | `false` |

## Example response

```
EGS EGS-TEST-1234 has been successfully onboarded.
```

## Response parameters

| Parameter | Type | Description | Example |
| - | - | - | - |
| `message` | string | The success or failure message for EGS onboarding. | `EGS EGS-TEST-1234 has been successfully onboarded.` |

If onboarding fails, see the CSR request messages in [Error messages](https://docs.complyance.io/legacy/v2/ksa/error-messages/#egs-onboarding-csr-request).

## Next step

Send your first document to the [Unify API](https://docs.complyance.io/legacy/v2/ksa/unify/).

Source: https://docs.complyance.io/legacy/v2/ksa/egs-onboarding/