---
title: "Creating preapproved orders - Amplia Reg"
description: "How to create preapproved Amplia Reg orders, already approved on creation, for electronic registration authorities that validate identity on their own."
canonical: "https://docs.lacunasoftware.com/en-us/articles/amplia-reg/integration/preapproved-orders"
locale: "en"
product: "Amplia Reg"
last_updated: "2026-10-08"
---

# Creating preapproved orders - Amplia Reg

A preapproved order is an order that is already approved when it is created. It is meant for electronic registration authorities: systems
that validate the holder's identity on their own, outside [Amplia Reg](https://docs.lacunasoftware.com/en-us/articles/amplia-reg), and only need the certificate to be issued.

A preapproved order skips validation and confirmation. It starts at **Waiting issue** (`WaitingIssue`), and the holder issues the
certificate with the issue link, as with any other order. See [How certificate issuance works](https://docs.lacunasoftware.com/en-us/articles/amplia-reg/issuance#4-issuance) for what happens
during issuance.

> **Tip**
>
> Make sure you have completed the [Getting started](https://docs.lacunasoftware.com/en-us/articles/amplia-reg/integration/get-started) steps

## Before you start

* **Role**: the application must have the **Electronic registration authority** role. This role creates preapproved orders and retrieves
  their issue keys. It does not create regular orders.
* **Registration authority**: preapproved orders are always created at a registration authority, and the certificate type must belong to
  the same certification authority as that registration authority. To choose the registration authority, pass its ID in the
  `X-Subscription` header (in .NET, the `RegistrationAuthorityId` option). If the API returns the `SubscriptionRequired` error, the
  request did not name a registration authority.
* **Certificate type**: list the certificate types available to you as described in [Create an order](https://docs.lacunasoftware.com/en-us/articles/amplia-reg/integration/create-order), and take note of
  the code of the one you want.

## Creating the order

The examples below create an ICP-Brasil e-CPF order. See [Other certificate formats](https://docs.lacunasoftware.com/en-us/articles/amplia-reg/integration/preapproved-orders#other-certificate-formats) for the other formats.

In .NET:

```cs
var response = await ampliaRegService.CreatePreApprovedOrderAsync(new CreatePreApprovedOrderOptions2<CreatePreApprovedOrderBrazilParameters>() {
	CertificateType = CertificateTypeReference.FromCode("ECPFA1"), // Certificate type code
	HolderType = HolderTypeReference.FromCode("PF"), // Holder type code (see "Holder documents" below)
	Validity = PeriodModel.FromYears(1), // Certificate validity (the certificate type must allow it)
	Parameters = new CreatePreApprovedOrderBrazilParameters() {
		Cpf = "07917307000", // Holder's CPF, digits only
		Name = "Holder Name", // Holder's full name
	},
	Contact = new ContactData() {
		EmailAddress = "holder@example.com",
		Phone = "+5511999990000",
	},
	HolderFiles = new List<HolderFileReference2>() {
		new HolderFileReference2() {
			Type = "Identification",
			Subtype = HolderFileSubtypes.Cnh,
			DocumentPart = DocumentParts.FrontComplete,
			File = FileReference.FromFile(@"C:\AppData\Documents\cnh.pdf"),
		},
	},
	NotifySubject = true, // Amplia Reg emails and texts issue key 2 to the holder
});
```

The .NET client uploads the files for you. See [Referencing files](https://docs.lacunasoftware.com/en-us/articles/amplia-reg/integration/file-referencing) for the ways to reference a file.

Via API, upload each file first with a `multipart/form-data` request containing the fields `file`, `name` and `contentType`:

```plaintext
POST /api/uploads
```

The response contains the `id` of the upload. Then create the order, referencing the uploaded files:

```js
POST /api/brazil/orders/pre-approved
X-Subscription: 3fa85f64-5717-4562-b3fc-2c963f66afa6 // Registration authority ID
{
	"certificateType": {
		"code": "ECPFA1" // Certificate type code
	},
	"holderType": {
		"code": "PF" // Holder type code
	},
	"validity": {
		"years": 1 // Certificate validity (the certificate type must allow it)
	},
	"parameters": {
		"cpf": "07917307000", // Holder's CPF, digits only
		"name": "Holder Name" // Holder's full name
	},
	"contact": {
		"emailAddress": "holder@example.com",
		"phone": "+5511999990000"
	},
	"holderFiles": [
		{
			"type": "Identification",
			"subtype": "Cnh",
			"documentPart": "FrontComplete",
			"file": {
				"id": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9", // ID returned by the upload
				"name": "cnh.pdf",
				"contentType": "application/pdf"
			}
		}
	],
	"notifySubject": true // Amplia Reg emails and texts issue key 2 to the holder
}
```

### Request fields

| Field | Required | Description |
|---|---|---|
| `certificateType` | Yes | Certificate type, by `code` or `id` |
| `holderType` | Sometimes | Holder type, by `code` or `id`. Required when the certificate type has the documents step enabled and allows more than one holder type. Not allowed when the documents step is disabled |
| `validity` | Sometimes | Certificate validity. Required when the certificate type has more than one validity option |
| `parameters` | Yes | Holder data. For ICP-Brasil: `cpf` and `name`, and optionally `annotation` (up to 100 characters), which goes into an organizational unit of the certificate when the certificate type is set up to include it |
| `contact` | Yes | Holder's `emailAddress` and `phone`, and optionally `alternativeEmailAddress` and `alternativePhone` |
| `holderFiles` | Sometimes | Holder documents. See [Holder documents](https://docs.lacunasoftware.com/en-us/articles/amplia-reg/integration/preapproved-orders#holder-documents) |
| `notifySubject` | No | If `true`, Amplia Reg sends issue key 2 and the issue link to the holder by email and SMS. Defaults to `false` |
| `number` | No | Order number of your choice (up to 50 characters). Only allowed if the instance has custom order numbers enabled; must be unique |
| `saleNumber` | No | Order number in your sales system (up to 50 characters). Only allowed, or required, according to the instance settings. Not available in the .NET client options |
| `csr` | No | Certificate request (PKCS #10) for the certificate, when the key pair was generated beforehand. Its key size must match the certificate type. With a CSR, the issue page does not generate a new key pair |
| `csrFileName` | No | File name of the CSR |

> **Note**
>
> CPF must be provided without punctuation (digits only) and with leading zeros, if any.

### Holder documents

When the certificate type has the documents step enabled, the order has a holder type, and the holder type defines which documents are
required and which are optional. Send every required document. If the certificate type also has the biometrics step enabled, a document
of type `Photo` is required too.

Each document has:

* `type`: the document type, such as `Identification`, `AddressProof` or `Photo`. Custom document types configured on the instance are
  prefixed with `@` (for example, `@CustomDoc1`). See [Add document types](https://docs.lacunasoftware.com/en-us/articles/amplia-reg/on-premises/add-doc-types).
* `subtype` and `documentPart` (optional): in ICP-Brasil, an `Identification` document can state which document it is (`Rg`, `Cnh`, `Dni`,
  `CTPS`, `Passport`, `RNE`, `CIN`, `OAB`, `CRC`, `CRM`, `ProfessionalLicense` or `Undefined`). When `subtype` is given, `documentPart` is
  required: `FrontComplete` or `BackComplete`, and also `Digital` for every subtype except `Rg`, `RNE` and `Undefined`.
* `file`: the file itself.

When the certificate type has the documents step disabled, do not send `holderFiles` or `holderType`.

Amplia Reg puts the documents into the order's dossier. If the instance has a seal certificate configured, Amplia Reg signs the dossier
and the holder's agreement with it.

## Response

```js
{
	"orderNumber": "800-005-520",
	"issueKey1": "48210937",
	"issueKey2": "77302156",
	"issueLink": "https://ar.example.com/issue?o=800-005-520",
	"issueLinkWithKey1": "https://ar.example.com/issue?o=800-005-520&k1=48210937",
	"issueLinkWithKeys": "https://ar.example.com/issue?o=800-005-520&k1=48210937&k2=77302156"
}
```

| Field | Description |
|---|---|
| `orderNumber` | Number of the order created |
| `issueKey1`, `issueKey2` | The two issue keys. If the instance uses a single issue key, `issueKey1` is `null` |
| `issueLink` | Issue link without keys: the holder types both keys |
| `issueLinkWithKey1` | Issue link with key 1 filled in: the holder types only key 2 |
| `issueLinkWithKeys` | Issue link with both keys filled in: the holder types nothing |

### Delivering the issue link to the holder

The holder needs the issue link and both keys. Choose how they get them:

* **Split across two channels (recommended)**: set `notifySubject` to `true`, so that Amplia Reg sends issue key 2 by email and SMS, and
  give the holder `issueLinkWithKey1` through your own system. Whoever intercepts one of the channels cannot issue the certificate alone.
* **All in your system**: leave `notifySubject` as `false` and show the holder `issueLinkWithKeys`, or `issueLink` together with both keys.

> **Warning**
>
> `issueLinkWithKeys` is enough to issue the certificate. Treat it as a secret: show it only to the holder, after they authenticate in your
> system, and never log it.

## Retrieving the issue links later

To get the keys and the issue links of a preapproved order again, for example to show them to the holder once more:

In .NET:

```cs
var preApprovedOrder = await ampliaRegService.GetPreApprovedOrderAsync("800-005-520");
```

Via API:

```plaintext
GET /api/orders/800-005-520/pre-approved
```

The response has the same fields as the creation response.

To have Amplia Reg send issue key 2 and the issue link to the holder again, call `SendCertificateIssueInstructionsAsync` in .NET, or:

```plaintext
POST /api/orders/800-005-520/notifications/certificate-issuance
```

The notification is sent only while the order is at **Waiting issue**, and not more than once per cooldown period (one minute by
default). Otherwise, the response's `failure` field says why (`NotWaitingIssue` or `CoolingDown`, with `canResendIn` in milliseconds).

## Following the order

Like any order created by your application, a preapproved order triggers [webhooks](https://docs.lacunasoftware.com/en-us/articles/amplia-reg/integration/webhooks) on every status change, from
**Waiting issue** at creation to **Issued** once the holder issues the certificate.

An order that has not been issued yet can be canceled in the control panel or through the [cancellation API](https://docs.lacunasoftware.com/en-us/articles/amplia-reg/integration/cancel-order). The
Electronic registration authority role cannot cancel orders: to cancel through the API, the application also needs the **Sales app**
role.

## Other certificate formats

The other certificate formats work the same way, with a different route and parameters class:

| Format | Route | Parameters class (.NET) |
|---|---|---|
| ICP-Brasil | `POST /api/brazil/orders/pre-approved` | `CreatePreApprovedOrderBrazilParameters` |
| Paraguay | `POST /api/paraguay/orders/pre-approved` | `CreatePreApprovedOrderParaguayParameters` |
| Cabo Verde | `POST /api/cabo-verde/orders/pre-approved` | `CreatePreApprovedOrderCaboVerdeParameters` |
| SSL | `POST /api/ssl/orders/pre-approved` | `CreatePreApprovedOrderSslParameters` |

See the [API documentation](https://ar.lacunasoftware.com/swagger) for the fields of each parameters class, or contact us.

## Common errors

| Code | Cause |
|---|---|
| `SubscriptionRequired` | The request did not name a registration authority |
| `CertificationAuthorityMismatch` | The certificate type belongs to a different certification authority than the registration authority |
| `HolderTypeIsRequired` | The certificate type allows more than one holder type and `holderType` was not given |
| `HolderTypeNotAllowed`, `CertificateTypeDoesNotAllowDocuments` | `holderType` or `holderFiles` were sent for a certificate type with the documents step disabled |
| `MissingRequiredHolderFileType` | A required document, or the photo, is missing |
| `HolderFileTypeCannotBeAdded` | A document type is not accepted by the holder type |
| `UnexpectedHolderFileSubtype`, `MissingRequiredDocumentPart` | Invalid `subtype`, or `subtype` without `documentPart` |
| `ValidityIsRequired` | The certificate type has more than one validity option and `validity` was not given |
| `CustomNumberNotAllowed`, `OrderNumberAlreadyExists` | `number` was sent but custom numbers are disabled, or the number is already in use |
| `SaleNumberNotAllowed`, `SaleNumberIsRequired` | `saleNumber` is not allowed, or is required, by the instance settings |
| `InvalidCsr` | The CSR could not be decoded |

## See also

* [Getting started with integration](https://docs.lacunasoftware.com/en-us/articles/amplia-reg/integration/get-started)
* [How certificate issuance works](https://docs.lacunasoftware.com/en-us/articles/amplia-reg/issuance)
* [File referencing](https://docs.lacunasoftware.com/en-us/articles/amplia-reg/integration/file-referencing)
* [Webhooks](https://docs.lacunasoftware.com/en-us/articles/amplia-reg/integration/webhooks)
* [Error codes](https://docs.lacunasoftware.com/en-us/articles/amplia-reg/integration/error-codes)