Skip to main content
This section describes an end-to-end flow to create a beneficiary. Please retreive this payload template using the List Products API. Here is an example :

​
1. Create instruction to add a beneficiary

​
Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/create'
--header 'company-identifier: ' \
--header 'submitter-id: ' \
--header 'request-identifier: ' \
--header 'request-timestamp: ' \
--header 'Content-Type: application/json' \
--header 'signature: ' \
--data-raw 
'{
    "serviceId": "0x0007-004",
    "payload": {
        "entityType": "INDIVIDUAL",
        "beneficiaryName": "John Smith",
        "registeredAddress": {
            "line1": "10 Downing Street",
            "city": "London",
            "country": "United Kingdom"
        },
        "operatingAddress": {
            "line1": "10 Downing Street",
            "city": "London",
            "country": "United Kingdom"
        }
    }
}'

​
Response

HTTP 200 
{
  "requestId": "SERV-REQ-Y3S874B6IC",
  "pluginDetail": {
    "entityId": "BNF-T20046-JQAPQMNOYA",
    "details": [
      {
        "entityType": "INDIVIDUAL",
        "legalName": "John Smith",
        "registeredAddress": {
          "line1": "10 Downing Street",
          "city": "London",
          "country": "United Kingdom"
        },
        "operatingAddress": {
          "line1": "10 Downing Street",
          "city": "London",
          "country": "United Kingdom"
        }
      }
    ]
  }
}

​
2. Submit service request

Use the request id obtained in the previous request to submit the instruction

​
Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/submit' \
--header 'company-identifier: ' \
--header 'submitter-id: ' \
--header 'request-identifier: ' \
--header 'request-timestamp: ' \
--header 'Content-Type: application/json' \
--header 'signature: ' \
--data '{
  "requestId": "SERV-REQ-Y3S874B6IC",
}'

​
Response

HTTP 200

​
3. Retrieve instruction to sign as maker

Retrieve the HSM instruction to be signed by the maker

​
Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/pending' \
--header 'company-identifier: ' \
--header 'submitter-id: ' \
--header 'request-identifier: ' \
--header 'request-timestamp: ' \
--header 'Content-Type: application/json' \
--header 'signature: ' \
--data '{
  "requestId": "SERV-REQ-Y3S874B6IC",
}'

​
Response

HTTP 200 
{
  "request": {
    ...
  },
  "signature": "$$REPLACE$$"
}

​
4. Confirm instruction as maker

Sign the ‘request’ element with the API maker private key, insert the string in ‘signature’. The signed instruction is submitted directly to the HSM.

​
Request

curl --request POST 'https://hostname.zodia.io/v3/api/servicedesk/approve' \
--header 'company-identifier: ' \
--header 'submitter-id: ' \
--header 'request-identifier: ' \
--header 'request-timestamp: ' \
--header 'Content-Type: application/json' \
--header 'signature: ' \
--data '{
  "requestId": "SERV-REQ-Y3S874B6IC",
  "request": {
    ...
  },
  "signature": "MEQCIAkTlKFSm8IDOS7o0eklI7aU9MvmS6vQUM6NElw9R3ebAiAPd8TMNh6g3QtzDYEPOFxa1EYCr3o+a5ypHa8/RLrN2w=="
}'

​
Response

HTTP 200
NOTE: Authoriser approval is not required when creating beneficiaries