Create a new request with a fixed document to sign

Copy

• 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

This API call enables you to create a new onboarding request with a document that requires a signature.

Note:

• There must be one signature field in the document.

To prepare a document with the correct signature fields, visit the following page: Prepare a module for signature

Endpoint

• URL: /requests
• Method: POST

Headers

Ensure you include the following headers in your request:

• Accept: application/json
• Content-Type: application/json
• X-Api-Key: YOUR_API_KEY (replace YOUR_API_KEY with your actual API key)

Query parameters

• idempotencyKey (optional): This query parameter ensures that the request is idempotent. If the endpoint has already received a request with the same IdempotencyKey in the last 7 days, it replies with the same body that was sent the first time. This prevents duplicate requests.

Body parameters

• requestTypeId: Identifier of the type of process associated with the request. This identifier is given to the Integrator during initial setup of the integration project.

• referenceId (optional): Field of the request that maps to an identifier relevant to the Integrator's system. It is not used internally by Namirial Onboarding but helps the integrator track and manage requests within their own systems

• <parameters>: If this part is empty, an anonymous request is being created. In the case of a request with a signature, which therefore requires the issuance of a disposable certificate, the parameters' email' and 'phoneNumber' are mandatory.

• settings (optional): here, it is possible to set some specific settings of the new request:

  • fillForm: a list that includes the identifiers of the AcroFields to be filled out. As shown in the example, you can use the user's name and surname to populate the designated fields in the document by propagating the identification data (using the identification keywords).

  • documentToSignTemplateUrl: The request settings include the document to be signed. In the

  • signForms: a list to specify the identifiers of the AcroFields to sign and the identified user who needs to sign. It is not mandatory to specify the signature field; if you do not pass that setting, it will sign all the signature fields it finds.

  • wizardUrlBack: URL to redirect the user when the process is complete
    Placeholders:

    • <requestId>
    • <referenceId>
    • <status>: final status of the request
    • <requestTypeId>
    • <actor>: is the role of the customer in the Namirial Onboarding process, usually userToIdentify

Example cURL API call

We can define a sample payload that includes all necessary fields for successfully testing an onboarding and signing process. The payload below is for illustrative purposes only.

curl --location 'https://test-eu-ie1-api.namirialonboarding.com/api/v2/requests' \
--header 'Content-Type: application/json' \
--header 'content-type: application/json' \
--header 'X-API-KEY: YOUR_API_KEY' \
--data-raw '{
  "requestTypeId": "123e4567-e89b-12d3-a456-426614174000",
  "referenceId": "YOUR_REFERENCE_ID",
    "parameters": {
        "email": "john.doe@mail.com",
        "phoneNumber": "+4300000000"
    },
    "settings": {
        "fillForm": [
            {
                "value": "${identification.firstName} ${identification.lastName}",
                "fieldId": "name"
            },
            {
                "value": "${identification.birthPlace}",
                "fieldId": "placeofbirth"
            },
            {
                "value": "${identification.birthDate}",
                "fieldId": "dateofbirth"
            },
            {
                "value": "${identification.personalNumber}",
                "fieldId": "fiscal_code"
            }
        ],

        "documentToSignTemplateUrl": "https://facematchfast-files.namirial.com/PreSales_DocumentoDiScopoV2.pdf"
    }
}'

Replace YOUR_API_KEY with your actual API key, YOUR_REFERENCE_ID with your reference, and YOUR_IDEMPOTENCY_KEY with the idempotency key of the request.

Responses

• 200 OK

  • Description: The draft request.
  • Example Response:

{
    "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "organizationId": "ff3c1cbb-6930-4ee6-xxxx-xxxxxxxxxxxxx",
    "status": "CREATED",
    "requestTypeId": "123e4567-e89b-12d3-a456-426614174000",
    "referenceId": "YOUR_REFERENCE_ID",
    "parameters": {
        "email": "john.doe@mail.com",
        "phoneNumber": "+4300000000"
    },
    "settings": {
        "fillForm": [
            {
                "value": "${identification.firstName} ${identification.lastName}",
                "fieldId": "name"
            },
            {
                "value": "${identification.birthPlace}",
                "fieldId": "placeofbirth"
            },
            {
                "value": "${identification.birthDate}",
                "fieldId": "dateofbirth"
            },
            {
                "value": "${identification.personalNumber}",
                "fieldId": "fiscal_code"
            }
        ]
    },
    "createdAt": "2025-08-20T13:58:19.056180544Z",
    "updatedAt": "2025-08-20T13:58:19.056180544Z",
    "expireAfter": "2025-09-19T13:58:19.055698596Z",
    "operatorPending": false,
    "links": [
        {
            "actor": "userToIdentify",
            "link": "https://onboarding.example/res/3949?ts=49943",
            "expiresAfter": "2025-09-19T13:58:19.055698596Z"
        }
    ]
}

Identification keywords

Other Keywords

There are additional keywords in the list to complete the document. Here is the additional list Keywords