# Prepare: CSR and approvers

> Generate or inspect a CSR, and list the approver e-mail addresses a certificate can be validated with. None of these calls charge.

## Step 0a — generate a CSR

### POST /api/v1/ssls/generate-csr

Generates a CSR and matching private key on our side. Optional — you may bring your own CSR to `configure` instead.

**Request**

```json
{
  "domainName": "apiname.com",
  "country": "TR",
  "state": "Istanbul",
  "locality": "Istanbul",
  "organization": "Apiname Ltd",
  "organizationUnit": "IT",
  "alternativeNames": ["www.apiname.com"]
}
```

| Field | Required | Max | Notes |
| --- | --- | --- | --- |
| `domainName` | required | 72 | The certificate's main name. For a wildcard certificate send `*.apiname.com`. |
| `country` | required | 2 | ISO 3166-1 alpha-2, uppercase. |
| `state` | required | 50 | State, province or region. Spell it out — no abbreviations. |
| `locality` | required | 50 | City. |
| `organization` | required | 150 | Legal entity name. **For OV and EV certificates this must match official records exactly** or vetting fails. |
| `organizationUnit` | required | 150 | Department, e.g. `IT`. |
| `alternativeNames` | optional | — | Extra names to embed in the CSR. |

**Response — 200**

```json
{
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICvDCCAaQCAQAwdzEL...\n-----END CERTIFICATE REQUEST-----",
  "privateKey": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhki...\n-----END PRIVATE KEY-----"
}
```

:::danger[Store the private key now — there is no second chance]
The private key is **not kept** unless you send it back in `configure`, and there is no endpoint that will return it later. Without it the issued certificate is useless and you will have to reissue.

Store it encrypted, alongside the CSR, against your customer's record — before you make the next API call.
:::

**Errors**

| Code | Meaning and fix |
| --- | --- |
| `Ssl:10001` | Invalid domain name. |
| `Ssl:10005` | The domain name does not meet the required format. Wildcards must have the `*` as the leftmost label only. |

## Step 0b — inspect a CSR

### POST /api/v1/ssls/check-csr

Decodes a CSR so you can confirm its contents before buying. Useful when the customer supplies their own.

**Request**

```json
{
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICvDCCAaQCAQAwdzEL...\n-----END CERTIFICATE REQUEST-----"
}
```

**Response — 200**

```json
{
  "domainName": "apiname.com",
  "country": "TR",
  "state": "Istanbul",
  "locality": "Istanbul",
  "organization": "Apiname Ltd",
  "organizationUnit": "IT",
  "alternativeNames": "www.apiname.com",
  "isWildcard": false,
  "isSan": true
}
```

:::tip[Use this to validate before charging]
Check `domainName` matches what the customer ordered, and that `isWildcard` matches the package type. A mismatch discovered here costs nothing; the same mismatch discovered at `configure` has already cost the certificate fee and started the 7-day clock.
:::

**Errors**

| Code | Meaning and fix |
| --- | --- |
| `Ssl:10004` | The CSR could not be decoded. Check it includes the BEGIN/END lines and has not been line-wrapped incorrectly. |

## Step 0c — approver e-mail addresses

### GET /api/v1/ssls/approvers

Lists the e-mail addresses the CA will accept as the domain's approver, for e-mail-based validation.

**Request**

```http
GET /api/v1/ssls/approvers?domainName=apiname.com&packageCode=POSITIVESSL
```

| Parameter | Required | Notes |
| --- | --- | --- |
| `domainName` | required |   |
| `packageCode` | conditional | **Required if no certificate exists yet** for this domain. Ignored once one does. |

**Response — 200**

```json
{
  "mails": [
    "admin@apiname.com",
    "administrator@apiname.com",
    "hostmaster@apiname.com",
    "postmaster@apiname.com",
    "webmaster@apiname.com"
  ]
}
```

:::tip[What to do with it]
Present this list to the customer and let them choose. The address they pick is what you send as `approverMail`. **An address not on this list is rejected** when `authenticationType` is `Email`.

If the customer has none of these mailboxes — common with a domain they just bought — use `Cname` or `Http` validation instead and skip this call.
:::

**Errors**

| Code | Meaning and fix |
| --- | --- |
| `Ssl:10038` | The approver list could not be retrieved from the CA. Retry, or use DNS/HTTP validation. |
| `Ssl:10003` | `packageCode` missing or unknown, and no certificate exists for the domain. |