# Create a new request with a document to sign This API call enables you to create a new onboarding request with a document to be signed. Let's start with the example [Create a new request with preset data](/products/namirialonboarding/namirial-onboarding-knowledge-center/03-developer-documentation/02-api-reference/01-requests-management/01-create-requests/create-a-new-request-with-preset-data) (but the one without preset data is fine too) by adding the possibility to upload documents for signing. The integration must follow these essential steps: 1. Create the request using the same endpoint as today by passing a query param `draft=true` 2. Then they will call an endpoint to upload a file and obtain as output a resource URI that will be used in the next calls 3. They will call the request endpoint to modify the draft request by passing in the input parameters, the URI of the uploaded file (where it is needed) 4. They will call the create endpoint, actually to move the request from draft state to create state (validation will happen here, and they will receive the actor links) Note: It is mandatory that there must be one signature field in the document. To prepare a document with the correct signature fields, visit the following page: [Prepare a document for signature](/products/namirialonboarding/namirial-onboarding-knowledge-center/02-products-and-modules/02-data-intelligence/03-signature-services/prepare_module_signature) ## Step 1: create the draft request ### 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 * `draft`: set to `true` * `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 system * `settings` (optional): Here, it is possible to set some specific settings of the new request: * `wizardUrlBack`: URL to redirect the user when the process is complete. Placeholders: * `` * `` * ``: final status of the request * `` * ``: is the role of the customer in the Namirial Onboarding process, usually `userToIdentify` ### Example cURL API call ``` curl -X POST "https://test-eu-ie1-api.namirialonboarding.com/api/v2/requests?draft=true&idempotencyKey=YOUR_IDEMPOTENCY_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "X-Api-Key: YOUR_API_KEY" \ -d '{ "requestTypeId": "123e4567-e89b-12d3-a456-426614174000", "referenceId": "YOUR_REFERENCE_ID", "parameters": { "firstName": "Mario", "lastName": "Rossi", "personalNumber": "RSSMR000000" }, "settings": { "wizardUrlBack": "https://webhook.site/2c47164f-fc65-44cd-a8c4-a2c806fb6c8a?requestId=&referenceId=&status=&requestTypeId=&actor=" } }' ``` 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. ## Step 2: Upload document ### 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) ### Example cURL API call ``` curl --location 'http://test-eu-ie1-api.namirialonboarding.com/api/v2/request/YOUR_REQUEST/upload' \ --header 'X-API-KEY: YOUR_API_KEY' \ --form 'resourceDescription="{\"filename\":\"tmp.pdf\",\"mimeType\":\"application/pdf\",\"name\":\"tmp.pdf\",\"type\":\"DOCUMENT\",\"subType\":\"DOCUMENT_FILLED\",\"family\":\"DOCUMENT_TO_SIGN\"}";type=application/json' \ --form 'file=@"/C:/Users/c.testi/Downloads/tmp.pdf"' ``` Replace YOUR_API_KEY with your actual API key, YOUR_REQUESTwith the identifier of the request created at the step 1 and the name “tmp” with the name of the file you uploaded ## Step 3: Update draft request ### Endpoint * **URL**: `/requests` * **Method**: `PUT` ### 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 * `create`: set to `false` * `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 system * `settings` (optional): Here, it is possible to set some specific settings of the new request: * `documentToSignTemplateUrl`: URL obtained at the step 2 > you need to add the link of the document to the step 1. Placeholders: * `` * `` * ``: final status of the request * `` * ``: is the role of the customer in the Namirial Onboarding process, usually `userToIdentify` ### Example cURL API call ``` curl --location 'https://test-eu-ie1-api.namirialonboarding.com/api/v2/request/YOUR_REQUEST?create=false' \ --header 'X-API-KEY: kUGMdByhYGl7b7h9BFFCSqlHu9vuCd1FRRKKdTmyHJ' \ --header 'Content-Type: application/json' \ --header 'X-Api-Service: YOUR_API_KEY' \ --data '{ "requestTypeId": "YOUR_REQUEST_TYPE_ID", "referenceId": "YOUR_REFERENCE_ID", "parameters": { "firstName": "Mario", "lastName": "Rossi", "personalNumber": "RSSMR000000" }, "settings": { "documentToSignTemplateUrl": "nor://0.rq/req/c51c2e6f-ef47-4e40-998e-xxxxxxx/res/714f06b1-55c9-4cc2-b2e5-xxxxxxx?fn=tmp.pdf&v=CBpV7_5A.wWNcOLdQbR_4ikWSAjqkLzk" } }' ``` Replace YOUR_API_KEY with your actual API key, YOUR_REFERENCE_ID with your reference, YOUR_REQUESTwith the identifier of the request created at the step 1 and YOUR_IDEMPOTENCY_KEY with the idempotency key of the request. ## Step 4: Publish a draft request ### 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) ### Example cURL API call ``` curl --location --request POST 'https://test-eu-ie1-api.namirialonboarding.com/api/v2/request/YOUR_REQUEST/creation' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'X-Api-Key: YOUR_API_KEY' ``` Replace YOUR_API_KEY with your actual API key and YOUR_REQUESTwith the identifier of the request created at the step 1.