DEVELOPER DOCUMENTATION

API Overview

Get disposable contract

Lean Disposable Services (26.1.0.3)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

REST API for enrolling and managing lean disposable certificates for secure digital signatures.

Authenticate every request with Basic Auth credentials and a client SSL certificate (mTLS). All requests require the Content-Type: application/json header.

For the full integration guide, see the Lean Disposable documentation.

Lean Disposable documentation

Download OpenAPI description

openapi.json

openapi.yaml

Servers

Production environment

https://lean.namirialtsp.com/RAWS_DISPOSABLE

Development and testing environment

https://lean.test.namirialtsp.com/RAWS_DISPOSABLE

Certificate

Methods to validate holder data, enroll disposable certificates, and send OTP codes.

Operations

Document

Methods to retrieve disposable contracts and upload documents related to the issued certificate.

Operations

Get AWS parameters

Request

Retrieves AWS credentials for the specified LRA and service. Used when a video identification process stores evidence on AWS. See getAwsParameter.

Security

basicAuth and sslCertificate

Path

lraIdstringrequired

Local Registration Authority (LRA) identifier.

Query

serviceIdstringrequired

The service name.

curl -i -X GET \
  -u <username>:<password> \
  'https://lean.namirialtsp.com/RAWS_DISPOSABLE/api/document/{lraId}/getAwsParameter?serviceId=string'

Responses

AWS credentials for the specified service.

Bodyapplication/json

serviceIdstring

The service name.

Example: "SERVICE_NAME"

arnstring

Amazon Resource Name (ARN) of the IAM role.

Example: "arn:aws:iam::000000000000:role/ExampleRole"

accessKeystring

AWS access key ID.

Example: "AKIAIOSFODNN0EXAMPLE"

secretAccessKeystring

AWS secret access key.

Example: "wJalrXUtnFEMI0K7MDENG0bPxRfiCYEXAMPLEKEY"

Response

application/json

{
  "serviceId": "SERVICE_NAME",
  "arn": "arn:aws:iam::000000000000:role/ExampleRole",
  "accessKey": "AKIAIOSFODNN0EXAMPLE",
  "secretAccessKey": "wJalrXUtnFEMI0K7MDENG0bPxRfiCYEXAMPLEKEY"
}

Get disposable contract

Request

Returns the disposable contract (Mod_NAMCA22D), the privacy document URL, and the T&C document URL for the specified LRA.

The contract is pre-filled with holder data if disposableHolder, disposableContacts and disposableDoc are all provided. If omitted, the contract is returned blank.

See getDisposableContract.

Security

basicAuth and sslCertificate

Path

lraIdstringrequired

Local Registration Authority (LRA) identifier.

Bodyapplication/jsonrequired

languageCodeArray of stringsrequired

Languages of the document. ISO 639-1 alpha-2 codes. You can specify more than one value.

Example: ["IT"]

docTypesArray of integers(int32)required

Type of document to return. 1 = PDF, 2 = TXT. You can specify more than one value.

Example: [1,2]

productTypestringrequired

Type of disposable certificate. See DisposableType.

Example: "DISPOSABLE"

countrystring

Country where the end user is located. ISO 3166-1 alpha-2 code. Optional — if not specified, the default template for the given languageCode is returned. Required when a LRA needs contracts in the same language but for different legislations (e.g. French contract for France vs Belgium).

Example: "IT"

disposableHolderobject(DisposableHolder)

Holder data. Optional — if provided together with disposableContacts and disposableDoc, the contract (Mod_NAMCA22D) is pre-filled.

disposableContactsobject(DisposableContacts)

Holder contact information. Required if otpType=SMS or otpType=EMAIL. Provide mobile if otpType=SMS, email if otpType=EMAIL.

disposableDocobject(DisposableDoc)

Identity document information.

Not required if one of the following conditions is true:

DisposableIdentification.identificationType is AML
DisposableHolder.identificationType is one of: PASSPORT, PERSONAL_NUMBER, NATIONAL_IDENTITY_CARD, DRIVING_LICENSE, RESIDENCE_PERMIT, RESIDENCE_PERMIT_TEMP, EMBASSY_DOCUMENT

disposableCertificateobject(DisposableCertificate)

Disposable Certificate configuration.

curl -i -X POST \
  -u <username>:<password> \
  'https://lean.namirialtsp.com/RAWS_DISPOSABLE/api/document/{lraId}/getDisposableContract' \
  -H 'Content-Type: application/json' \
  -d '{
    "languageCode": [
      "EN"
    ],
    "docTypes": [
      1
    ],
    "productType": "DISPOSABLE"
  }'

Responses

Bodyapplication/jsonArray [

languageCodestring

Language of the document. ISO 639-1 alpha-2 code.

Example: "IT"

docTypesinteger(int32)

Document type. 1 = PDF, 2 = TXT.

Example: 2

docstring(binary)

Base64-encoded document (Mod_NAMCA22D). Pre-filled with holder data if disposableHolder, disposableContacts and disposableDoc were provided in the request.

privacy_linkstring

URL to download the privacy document (Mod_NAMGDPR03D).

Example: "https://docs.namirialtsp.com/documents/Mod_NAM_GDPR03D_ITA_IT.pdf"

termsAndConditions_linkstring

URL to download the terms and conditions document (Mod_NAMCA01D).

Example: "https://docs.namirialtsp.com/documents/Mod_NAM_CA01D_ITA_IT.pdf"

checkBoxesArray of strings

List of checkbox label strings to be displayed to the user for acceptance.

]

Response

application/json

[
  {
    "languageCode": "EN",
    "docTypes": 1,
    "doc": "<base64-encoded PDF>",
    "privacy_link": "https://docs.namirialtsp.com/documents/Mod_NAM_GDPR03D_ENG_IT.pdf",
    "termsAndConditions_link": "https://docs.namirialtsp.com/documents/Mod_NAM_CA01D_ENG_IT.pdf",
    "checkBoxes": [ … ]
  }
]

Get disposable contract with eID assertion

Request

Retrieves disposable contract documents (Mod_NAMCA22D) using an eID assertion. Returns contract PDF/TXT, privacy document URL (Mod_NAMGDPR03D), and T&C document URL (Mod_NAMCA01D). The contract is pre-filled if eIDAssertionHolder and contacts are provided. See getDisposableContractWitheIDAssertion and How to enroll with eID assertion.

Security

basicAuth and sslCertificate

Path

lraIdstringrequired

Local Registration Authority (LRA) identifier.

Bodyapplication/jsonrequired

eIDAssertionHolderobject(DisposableeIDAssertionHolder)

eID assertion holder data. The country and eIDType together identify the eID method (e.g., IT-SPID, IT-EIDNAMIRIAL, AT-EID). The assertion format depends on the eID type.

certobject(DisposableCertificate)required

Certificate configuration. Specifies certificate type and options.

cert.passwordstring[ 8 .. 32 ] characters^[A-Za-z0-9]+$required

Certificate PIN.

cert.securityCodestring[ 8 .. 32 ] characters^[A-Za-z0-9]+$required

Certificate security code.

cert.fullDataboolean

Enroll with full profile. Default: false.

cert.withoutUsageLimitLRAboolean

Omit LRA limitation of use (LoU). Default: false.

cert.typestring(DisposableType)

Disposable certificate type. See allowed values. Default: DISPOSABLE.

Enum"DISPOSABLE""DISPOSABLE_30_DAYS""LONG_LIVED""DISPOSABLE_FEA"

cert.otpTypestring(DisposableOtpType)

OTP delivery method. See allowed values. Default: SMS.

Enum"SMS""EMAIL""NO_OTP""EXTERNAL_OTP"

cert.transactionLimitobject(TransactionLimit)

cert.limitationOfUseobject(LimitationOfUse)

contactsobject(DisposableContacts)

Holder contact information. Required if otpType=SMS or otpType=EMAIL. Provide mobile if otpType=SMS, email if otpType=EMAIL.

languageCodeArray of stringsrequired

Languages of the document. ISO 639-1 alpha-2 codes. You can specify multiple values.

Example: ["EN"]

docTypesArray of integers(int32)required

Document types. Allowed values: 1 (PDF), 2 (TXT). You can specify multiple values.

Example: [1]

countrystring^[A-Z]{2}$

Country code where the final user is located. ISO 3166-1 alpha-2 code. Optional — if not specified, the default template for the specified languageCode is returned. Required when a LRA needs contracts in several languages but for different legislations (e.g., French contract for France vs. French contract for Belgium).

Example: "IT"

curl -i -X POST \
  -u <username>:<password> \
  'https://lean.namirialtsp.com/RAWS_DISPOSABLE/api/document/{lraId}/getDisposableContractWitheIDAssertion' \
  -H 'Content-Type: application/json' \
  -d '{
    "eIDAssertionHolder": {
      "country": "IT",
      "eIDType": "EIDNAMIRIAL",
      "assertion": "eyJnaXZlbl9uYW1lIjoiTWFyaW8iLCJmYW1pbHlfbmFtZSI6IlJvc3NpIiwicGVyc29uX2lkZW50aWZpZXIiOiJUSU5JVC1SU1NNUkE4MEEwMUg1MDFVIiwiYmlydGhfZGF0ZSI6IjE5ODAtMDEtMDEiLCJkb2NfdHlwZSI6Ik5BVElPTkFMX0lERU5USVRZX0NBUkQiLCJjb3VudHJ5IjoiSVQiLCJycF9uYW1lIjoiTmFtaXJpYWwgVGVzdCBSUCIsInJwX2lkIjoidGVzdC1ycC0wMDEiLCJvcmlnaW5hbF9hc3NlcnRpb24iOiJiYXNlNjRfZW5jb2RlZF9zYW1sX2Fzc2VydGlvbl9oZXJlIiwiaWF0IjoxNzA5NTY4MDAwfQ=="
    },
    "contacts": {
      "mobile": "+390000000000",
      "email": "example@example.com"
    },
    "cert": {
      "type": "DISPOSABLE",
      "password": "Password01",
      "securityCode": "Security01",
      "withoutUsageLimitLRA": false
    },
    "languageCode": [
      "EN"
    ],
    "docTypes": [
      1
    ]
  }'

Responses

Contract documents retrieved successfully. Returns an array of contract documents (Mod_NAMCA22D) with privacy and T&C links. The contract is pre-filled if eIDAssertionHolder and contacts are provided.

Bodyapplication/jsonArray [

languageCodestring

Language of the document. ISO 639-1 alpha-2 code.

Example: "IT"

docTypesinteger(int32)

Document type. 1 = PDF, 2 = TXT.

Example: 2

docstring(binary)

Base64-encoded document (Mod_NAMCA22D). Pre-filled with holder data if disposableHolder, disposableContacts and disposableDoc were provided in the request.

privacy_linkstring

URL to download the privacy document (Mod_NAMGDPR03D).

Example: "https://docs.namirialtsp.com/documents/Mod_NAM_GDPR03D_ITA_IT.pdf"

termsAndConditions_linkstring

URL to download the terms and conditions document (Mod_NAMCA01D).

Example: "https://docs.namirialtsp.com/documents/Mod_NAM_CA01D_ITA_IT.pdf"

checkBoxesArray of strings

List of checkbox label strings to be displayed to the user for acceptance.

]

Response

application/json

[
  {
    "languageCode": "IT",
    "docTypes": 2,
    "doc": "string",
    "privacy_link": "https://docs.namirialtsp.com/documents/Mod_NAM_GDPR03D_ITA_IT.pdf",
    "termsAndConditions_link": "https://docs.namirialtsp.com/documents/Mod_NAM_CA01D_ITA_IT.pdf",
    "checkBoxes": [ … ]
  }
]

Upload AWS document ID

Request

Associates an AWS identification reference to an issued disposable certificate. Used when a video identification process stores evidence on AWS.

See uploadAwsId.

Security

basicAuth and sslCertificate

Path

lraIdstringrequired

Local Registration Authority (LRA) identifier.

Bodyapplication/jsonrequired

awsIdstringrequired

AWS identification reference for the video identification evidence.

Example: "HgI1MM8VuxpoXh6xozcd0gU8rPCvUN6c9HJRY27-K9A2hRm9ZVFFsVx2whuohH63"

deviceCodestringrequired

Device code of the issued certificate, returned by enroll (deviceCode).

Example: "RHIDP0000000000000"

idOtpinteger(int32)required

OTP certificate identifier returned by enroll (certIdOtp).

Example: 1234567

externalKeystring

Optional external reference key.

Example: "external_key_sample"

curl -i -X POST \
  -u <username>:<password> \
  'https://lean.namirialtsp.com/RAWS_DISPOSABLE/api/document/{lraId}/uploadAwsId' \
  -H 'Content-Type: application/json' \
  -d '{
    "awsId": "HgI1MM8VuxpoXh6xozcd0gU8rPCvUN6c9HJRY27-K9A2hRm9ZVFFsVx2whuohH63",
    "deviceCode": "RHIDP0000000000000",
    "idOtp": 1234567,
    "externalKey": "external_key_sample"
  }'

Responses

AWS ID uploaded successfully. Response body is empty.

Response

No content

Upload document

Request

Stores a document linked to an issued disposable certificate. Supported document types: identification evidence, signed contracts (e.g. CA22D), audit logs, identity assertions.

Note: if the disposable was issued with enrollDisposableWitheIDAssertion, the assertion is stored automatically — do not upload it with this method.

See uploadDoc.

Security

basicAuth and sslCertificate

Path

lraIdstringrequired

Local Registration Authority (LRA) identifier.

Bodyapplication/jsonrequired

deviceCodestringrequired

Device code of the issued certificate, returned by enroll (deviceCode).

Example: "RHIDP0000000000000"

idOtpinteger(int32)

OTP certificate identifier returned by enroll (certIdOtp). Use 0 if the disposable has otpType=NO_OTP.

Example: 1234567

typeDocstringrequired

Type of document to upload.

Enum"IDENTIFICATION_DOC""CONTRACT""AUDIT_LOG""IDENTITY_ASSERTION"

Example: "CONTRACT"

extensionstringrequired

File extension (not case-sensitive). Allowed values: pdf, zip, png, jpeg, jpg, docx, doc, odt, xml, json, txt, mp4, m4a, m4v.

Example: "pdf"

filestringrequired

Base64-encoded file content.

Example: "<base64-encoded file>"

externalKeystring

Optional external reference key.

Example: "external_key_sample"

curl -i -X POST \
  -u <username>:<password> \
  'https://lean.namirialtsp.com/RAWS_DISPOSABLE/api/document/{lraId}/uploadDoc' \
  -H 'Content-Type: application/json' \
  -d '{
    "deviceCode": "RHIDP0000000000000",
    "idOtp": 1234567,
    "typeDoc": "CONTRACT",
    "extension": "pdf",
    "file": "<base64-encoded PDF>"
  }'

Responses

Bodyapplication/json

deviceCodestring

Device code of the certificate the document is linked to.

Example: "RHIDP0000000000000"

filenamestring

Server-generated filename for the uploaded document.

Example: "1234567_a4ece4b3e9626ccfd3bac2eb77c0c1d7950be77e190a64fcf1957279e677ffc7.pdf"

typeDocstring

Type of the uploaded document.

Enum"IDENTIFICATION_DOC""CONTRACT""AUDIT_LOG""IDENTITY_ASSERTION"

Example: "CONTRACT"

externalKeystring or null

External reference key, if provided in the request. null if not provided.

Example: "external_key_sample"

uploadDateinteger(int64)

Upload timestamp in epoch milliseconds.

Example: 1733496805136

Response

application/json

{
  "deviceCode": "RHIDP0000000000000",
  "filename": "1234567_a4ece4b3e9626ccfd3bac2eb77c0c1d7950be77e190a64fcf1957279e677ffc7.pdf",
  "typeDoc": "CONTRACT",
  "externalKey": null,
  "uploadDate": 1733496805136
}

Utility

Methods to verify service status and retrieve error information.

Operations

Certificate

Document

Get AWS parameters

Request

Responses

Was this helpful?

Get disposable contract

Request

Responses

Was this helpful?

Get disposable contract with eID assertion

Request

Responses

Was this helpful?

Upload AWS document ID

Request

Responses

Was this helpful?

Upload document

Request

Responses

Was this helpful?

Utility

Lean Disposable Services (26.1.0.3)CopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from ClaudeConnect to CursorInstall MCP server on CursorConnect to VS CodeInstall MCP server on VS Code

Certificate

Document

Get AWS parameters

Request

Responses

Was this helpful?

Get disposable contract

RequestExpand all

Responses

Was this helpful?

Get disposable contract with eID assertion

RequestExpand all

Responses

Was this helpful?

Upload AWS document ID

Request

Responses

Was this helpful?

Upload document

Request

Responses

Was this helpful?

Utility

Request

Request