Content Comparison

This API call allows you to create a new onboarding 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

• IdempotencyKey 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
    Placehoders:

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

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": "order-1234-0002",
  "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:

    Code Block
    language json
    { "id": "123e4567-e89b-12d3-a456-426614174001", "organizationId": "123e4567-e89b-12d3-a456-426614174002", "status": "CREATED", "referenceId": "order-1234-0002", "requestTypeId": "123e4567-e89b-12d3-a456-426614174000", "createdAt": "2024-10-29T17:42:16Z16.269594Z", "updatedAt": "2024-10-29T17:42:16Z16.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:16Z"16.269594Z" } ] }

• 400 Bad Request

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

  • Example Response:

    Code Block
    language json
    { "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" } ] }