Create a new request with preset data

This API call allows you to create a new onboarding request. The request includes all necessary information and parameters required to initiate the onboarding process.

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 to 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

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

  • wizardUrlBack: url to redirect the user when the process is complete

Example cURL API call

curl -X POST "https://test.onboarding.namirial.app/api/v2/requests?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": {
    "customerName": "John Doe",
    "customerEmail": "john.doe@example.com"
  },
  "settings": {
    "wizardUrlBack": "https://webhook.site/2c47164f-fc65-44cd-a8c4-a2c806fb6c8a?requestId=<requestId>&referenceId=<referenceId>&status=<status>&requestTypeId=<requestTypeId>&actor=<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.

Responses

• 200 OK

  • Description: The created request.

  • Example Response:

    {
      "id": "123e4567-e89b-12d3-a456-426614174001",
      "organizationId": "123e4567-e89b-12d3-a456-426614174002",
      "status": "CREATED",
      "referenceId": "order-1234-0002",
      "requestTypeId": "123e4567-e89b-12d3-a456-426614174000",
      "parameters": {
        "customerName": "John Doe",
        "customerEmail": "john.doe@example.com"
      },
      "createdAt": "2024-10-29T17:42:16.269594Z",
      "updatedAt": "2024-10-29T17:42:16.269594Z",
      "finalizedAt": null,
      "expireAfter": "2024-11-29T17:42:16.269594Z",
      "links": [
        {
          "actor": "customer",
          "link": "https://onboarding.example/res/3949?ts=49943",
          "expiresAfter": "2024-11-29T17:42:16.269594Z"
        }
      ]
    }

• 400 Bad Request

  • Description: Bad Request described following Problem Details (RFC 9457).

  • Example Response:

    {
      "type": "about:blank",
      "status": 400,
      "title": "Request validation error",
      "detail": "The has a malformed body property.",
      "instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000?ts=1729667463",
      "retryable": false,
      "errors": [
        {
          "detail": "Property 'dummyField' is not defined in the schema and the schema does not allow additional properties.",
          "pointer": "/parameters/dummyField",
          "field": "dummyField",
          "reason": "additionalProperties"
        }
      ]
    }