Digital Convergence Initiative
API docs by Redocly

Interoperability APIs - Employment Support System (1.0.0)

Download OpenAPI specification:Download

DCI Social Protection: info@spdci.org License: DCI Social Protection License

The ESS(Employment Support System) interoperability APIs describes different APIs some of them are usecase specific and other are generalized APIs to perform interoperable operations between ESS and SP-System. You can now help us improve the API whether it's by making changes to the definition itself or to the code. That way, with time, we can improve the API in general, and expose some of the new features in upcoming version.

  1. Search: The Search API provides functionality to search based on demographic, identifiers and custom query
  2. checkEnrolment : the check-enrolled API is a special type of search to return the enrolment status , can be executed from SP to ESS or vice versa

Gitbook reference link[WIP]:

Code directory links:

Data Objects:

Each request is build up of three parts

  • signature
  • header
  • message

Information about each part is given below

Signature:

  • The signature is used to verify the integrity of the message.
  • The signature is a hash of the message and is encrypted using the private key of the sender.
  • The receiver can verify the signature using the public key of the sender.

Header:

  • The header contains information about various message header, refer to the header schema for more details.

Message:

  • The message contains the actual payload of the message.
  • Refer example section to get sample data and also read Gitbook for details data objects
  • The receiver can decrypt the message using the private key of the "err.receiver_id.invalid"

Async

Async endpoints

/registry/subscribe

Subscribe to a change event with registry

Authorizations:
Authorization
Request Body schema:
required
signature
string (MsgSignature)

Signature of {header}+{message} body verified using sender's signing public key

required
object

Message header

required
SubscribeRequest (object) or EncryptedMessage (object)

Subscription request which contain query with frequency and other info on which notification to be sent by registry to subscriber

Responses

Request samples

Content type
{
  • "signature": "Signature: namespace=\"spdci\", kidId=\"{sender_id}|{unique_key_id}|{algorithm}\", algorithm=\"ed25519\", created=\"1606970629\", expires=\"1607030629\", headers=\"(created) (expires) digest\", signature=\"Base64(signing content)",
  • "header": {},
  • "message": {
    }
}

Response samples

Content type
application/json
{
  • "message": {
    }
}

/registry/on-subscribe

Subscribe results through callback

Authorizations:
Authorization
Request Body schema:
required
signature
string (MsgSignature)

Signature of {header}+{message} body verified using sender's signing public key

required
object

Message header

required
SubscribeResponse (object) or EncryptedMessage (object)

Subscription information

Responses

Request samples

Content type
{
  • "signature": "Signature: namespace=\"spdci\", kidId=\"{sender_id}|{unique_key_id}|{algorithm}\", algorithm=\"ed25519\", created=\"1606970629\", expires=\"1607030629\", headers=\"(created) (expires) digest\", signature=\"Base64(signing content)",
  • "header": {},
  • "message": {
    }
}

Response samples

Content type
application/json
{
  • "message": {
    }
}

/registry/notify

Registry to notify an event to subscribers

Authorizations:
Authorization
Request Body schema:
required
signature
string (MsgSignature)

Signature of {header}+{message} body verified using sender's signing public key

required
object

Message header

NotifyEventRequest (object) or EncryptedMessage (object)

Responses

Request samples

Content type
{
  • "signature": "Signature: namespace=\"spdci\", kidId=\"{sender_id}|{unique_key_id}|{algorithm}\", algorithm=\"ed25519\", created=\"1606970629\", expires=\"1607030629\", headers=\"(created) (expires) digest\", signature=\"Base64(signing content)",
  • "header": {
    },
  • "message": {
    }
}

Response samples

Content type
application/json
{
  • "message": {
    }
}

/registry/unsubscribe

Unsubscribe existing subscription(s) by subscription_code

Authorizations:
Authorization
Request Body schema:
required
signature
string (MsgSignature)

Signature of {header}+{message} body verified using sender's signing public key

required
object

Message header

required
UnSubscribeRequest (object) or EncryptedMessage (object)

The unsubscribe request that contain subscription ids which to be removed from subscription list

Responses

Request samples

Content type
{
  • "signature": "Signature: namespace=\"spdci\", kidId=\"{sender_id}|{unique_key_id}|{algorithm}\", algorithm=\"ed25519\", created=\"1606970629\", expires=\"1607030629\", headers=\"(created) (expires) digest\", signature=\"Base64(signing content)",
  • "header": {},
  • "message": {
    }
}

Response samples

Content type
application/json
{
  • "message": {
    }
}

/registry/on-unsubscribe

Unsubscribe response as a callback

Authorizations:
Authorization
Request Body schema:
required
signature
string (MsgSignature)

Signature of {header}+{message} body verified using sender's signing public key

required
object

Message header

required
UnSubscribeResponse (object) or EncryptedMessage (object)

Responses

Request samples

Content type
{
  • "signature": "Signature: namespace=\"spdci\", kidId=\"{sender_id}|{unique_key_id}|{algorithm}\", algorithm=\"ed25519\", created=\"1606970629\", expires=\"1607030629\", headers=\"(created) (expires) digest\", signature=\"Base64(signing content)",
  • "header": {},
  • "message": {
    }
}

Response samples

Content type
application/json
{
  • "message": {
    }
}

/registry/txn/status

The /registry/txn/status will be implemented by ESS or SP-System. This will check status of reach request using transaction_id and/or reference_id(s).

Authorizations:
Authorization
Request Body schema:
required
signature
string (MsgSignature)

Signature of {header}+{message} body verified using sender's signing public key

required
object

Message header

required
TxnStatusRequest (object) or EncryptedMessage (object)

Responses

Request samples

Content type
{
  • "signature": "Signature: namespace=\"spdci\", kidId=\"{sender_id}|{unique_key_id}|{algorithm}\", algorithm=\"ed25519\", created=\"1606970629\", expires=\"1607030629\", headers=\"(created) (expires) digest\", signature=\"Base64(signing content)",
  • "header": {},
  • "message": {
    }
}

Response samples

Content type
application/json
{
  • "message": {
    }
}

/registry/txn/on-status

The /registry/txn/on-status will be implemented by receiver system. The response with information about request and in some case it may contain data as well.

Authorizations:
Authorization
Request Body schema:
required
signature
string (MsgSignature)

Signature of {header}+{message} body verified using sender's signing public key

required
object

Message header

TxnStatusResponse (object) or EncryptedMessage (object)

Responses

Request samples

Content type
{
  • "signature": "Signature: namespace=\"spdci\", kidId=\"{sender_id}|{unique_key_id}|{algorithm}\", algorithm=\"ed25519\", created=\"1606970629\", expires=\"1607030629\", headers=\"(created) (expires) digest\", signature=\"Base64(signing content)",
  • "header": {
    },
  • "message": {
    }
}

Response samples

Content type
application/json
{
  • "message": {
    }
}

Sync

Sync endpoints

/registry/sync/check-enrollment

check status of a person if remain enrolled

Request Body schema:
required
signature
string (MsgSignature)

Signature of {header}+{message} body verified using sender's signing public key

required
object

Message header

required
EnrolledRequest (object) or EncryptedMessage (object)

The search data using which registry search to be performed

Responses

Request samples

Content type
{
  • "signature": "Signature: namespace=\"spdci\", kidId=\"{sender_id}|{unique_key_id}|{algorithm}\", algorithm=\"ed25519\", created=\"1606970629\", expires=\"1607030629\", headers=\"(created) (expires) digest\", signature=\"Base64(signing content)",
  • "header": {
    },
  • "message": {
    }
}

Response samples

Content type
application/json
{
  • "signature": "Signature: namespace=\"spdci\", kidId=\"{sender_id}|{unique_key_id}|{algorithm}\", algorithm=\"ed25519\", created=\"1606970629\", expires=\"1607030629\", headers=\"(created) (expires) digest\", signature=\"Base64(signing content)",
  • "header": {
    },
  • "message": {
    }
}

SearchRequest

transaction_id
required
string <= 99 characters
  1. transaction_id set by txn initiating system (i.e sender) to co-relate all related requests in the context of a business transaction.
  2. transaction_id should be same across processing systems/service end points.
  3. transaction_id uniqueness is ensured by txn initiating system (i.e sender)
required
Array of objects
  1. Batch requests enable multiple individual requests with respective consent/authorize codes
{
  • "transaction_id": "XZFHYTY",
  • "search_request": [
    ]
}

SearchResponse

transaction_id
required
string <= 99 characters
  1. transaction_id set by txn initiating system (i.e sender) to co-relate all related requests in the context of a business transaction.
  2. transaction_id should be same across processing systems/service end points.
  3. transaction_id uniqueness is ensured by txn initiating system (i.e sender)
correlation_id
required
string <= 99 characters ^[a-zA-Z0-9-]+$
  1. correlation_id acknowledged by end txn processing system (i.e receiver) to co-relate all related requests in the context of a business transaction.
  2. correlation_id uniqueness is ensured by txn processing system (i.e receiver)
required
Array of objects
{
  • "transaction_id": "XZFHYTY",
  • "correlation_id": "ABC9876543210",
  • "search_response": [
    ]
}

SubscribeRequest

transaction_id
required
string <= 99 characters
  1. transaction_id set by txn initiating system (i.e sender) to co-relate all related requests in the context of a business transaction.
  2. transaction_id should be same across processing systems/service end points.
  3. transaction_id uniqueness is ensured by txn initiating system (i.e sender)
required
Array of objects
{
  • "transaction_id": "XZFHYTY",
  • "subscribe_request": [
    ]
}

SubscribeResponse

transaction_id
required
string <= 99 characters
  1. transaction_id set by txn initiating system (i.e sender) to co-relate all related requests in the context of a business transaction.
  2. transaction_id should be same across processing systems/service end points.
  3. transaction_id uniqueness is ensured by txn initiating system (i.e sender)
correlation_id
required
string <= 99 characters ^[a-zA-Z0-9-]+$
  1. correlation_id acknowledged by end txn processing system (i.e receiver) to co-relate all related requests in the context of a business transaction.
  2. correlation_id uniqueness is ensured by txn processing system (i.e receiver)
required
Array of objects
{
  • "transaction_id": "XZFHYTY",
  • "correlation_id": "ABC9876543210",
  • "subscribe_response": [
    ]
}

NotifyEventRequest

transaction_id
required
string <= 99 characters
  1. transaction_id set by txn initiating system (i.e sender) to co-relate all related requests in the context of a business transaction.
  2. transaction_id should be same across processing systems/service end points.
  3. transaction_id uniqueness is ensured by txn initiating system (i.e sender)
required
Array of objects
{
  • "transaction_id": "XZFHYTY",
  • "notify_event": [
    ]
}

UnSubscribeRequest

transaction_id
required
string <= 99 characters
  1. transaction_id set by txn initiating system (i.e sender) to co-relate all related requests in the context of a business transaction.
  2. transaction_id should be same across processing systems/service end points.
  3. transaction_id uniqueness is ensured by txn initiating system (i.e sender)
timestamp
required
string <date-time>
  1. All dates and timestamps are represented in ISO 8601 format including timezone - e.g 2022-12-04T17:20:07-04:00.
subscription_codes
required
Array of strings (SubscriptionCode) [ items <= 99 characters ]
{
  • "transaction_id": "XZFHYTY",
  • "timestamp": "2022-12-04T17:20:07-04:00",
  • "subscription_codes": [
    ]
}

UnSubscribeResponse

transaction_id
required
string <= 99 characters
  1. transaction_id set by txn initiating system (i.e sender) to co-relate all related requests in the context of a business transaction.
  2. transaction_id should be same across processing systems/service end points.
  3. transaction_id uniqueness is ensured by txn initiating system (i.e sender)
correlation_id
required
string <= 99 characters ^[a-zA-Z0-9-]+$
  1. correlation_id acknowledged by end txn processing system (i.e receiver) to co-relate all related requests in the context of a business transaction.
  2. correlation_id uniqueness is ensured by txn processing system (i.e receiver)
timestamp
required
string <date-time>
  1. All dates and timestamps are represented in ISO 8601 format including timezone - e.g 2022-12-04T17:20:07-04:00.
status
required
string
Enum: "rcvd" "pdng" "succ" "rjct"

Request (e.g disburse, link, unlink, resolve, issue, search, verify, etc.,) status:
1. rcvd: Received; Request received
2. pdng: Pending; Request initiated
3. succ: Success; Request successful
4. rjct: Rejected; Request rejected

status_reason_code
string (UnSubscribeStatusReasonCode)
Enum: "rjct.reference_id.invalid" "rjct.reference_id.duplicate" "rjct.timestamp.invalid" "rjct.subscription_code.invalid" "rjct.requester.invalid" "rjct.event.already_unsubscribed"

Identity verification request status reason codes

status_reason_message
string <= 999 characters

Status reason code message. Helps actionanble messaging for systems/end users

Array of objects
{
  • "transaction_id": "XZFHYTY",
  • "correlation_id": "ABC9876543210",
  • "timestamp": "2022-12-04T17:20:07-04:00",
  • "status": "rcvd",
  • "status_reason_code": "rjct.reference_id.invalid",
  • "status_reason_message": "string",
  • "subscription_status": [
    ]
}

EnrolledRequest

transaction_id
required
string <= 99 characters
  1. transaction_id set by txn initiating system (i.e sender) to co-relate all related requests in the context of a business transaction.
  2. transaction_id should be same across processing systems/service end points.
  3. transaction_id uniqueness is ensured by txn initiating system (i.e sender)
required
object

Enrolled query

{
  • "transaction_id": "XZFHYTY",
  • "enrolled_criteria": {
    }
}

EnrolledResponse

transaction_id
required
string <= 99 characters
  1. transaction_id set by txn initiating system (i.e sender) to co-relate all related requests in the context of a business transaction.
  2. transaction_id should be same across processing systems/service end points.
  3. transaction_id uniqueness is ensured by txn initiating system (i.e sender)
correlation_id
required
string <= 99 characters ^[a-zA-Z0-9-]+$
  1. correlation_id acknowledged by end txn processing system (i.e receiver) to co-relate all related requests in the context of a business transaction.
  2. correlation_id uniqueness is ensured by txn processing system (i.e receiver)
required
Array of objects
{
  • "transaction_id": "XZFHYTY",
  • "correlation_id": "ABC9876543210",
  • "enrolled_response": [
    ]
}

TxnStatusRequest

transaction_id
required
string <= 99 characters
  1. transaction_id set by txn initiating system (i.e sender) to co-relate all related requests in the context of a business transaction.
  2. transaction_id should be same across processing systems/service end points.
  3. transaction_id uniqueness is ensured by txn initiating system (i.e sender)
required
object
{
  • "transaction_id": "XZFHYTY",
  • "txnstatus_request": {
    }
}

TxnStatusResponse

transaction_id
required
string <= 99 characters
  1. transaction_id set by txn initiating system (i.e sender) to co-relate all related requests in the context of a business transaction.
  2. transaction_id should be same across processing systems/service end points.
  3. transaction_id uniqueness is ensured by txn initiating system (i.e sender)
correlation_id
required
string <= 99 characters ^[a-zA-Z0-9-]+$
  1. correlation_id acknowledged by end txn processing system (i.e receiver) to co-relate all related requests in the context of a business transaction.
  2. correlation_id uniqueness is ensured by txn processing system (i.e receiver)
required
object
{
  • "transaction_id": "XZFHYTY",
  • "correlation_id": "ABC9876543210",
  • "txnstatus_response": {
    }
}

EncryptedMessage

required
object
ciphertext
required
string

This is the result of encrypting the plaintext using the CEK and the IV. It's Base64Url-encoded.

encrypted_key
required
string

The base64-url encoded encrypted key

tag
required
string

This is a Base64Url-encoded value that provides evidence of the integrity and authenticity of the ciphertext, Initialization Vector, and Additional Authenticated Data

iv
required
string

This is a Base64Url-encoded random bit string to be used as the Initialization Vector (IV) when encrypting the plaintext to produce the ciphertext. The size of the IV depends on the encryption algorithm used.

{
  • "header": {
    },
  • "ciphertext": "string",
  • "encrypted_key": "string",
  • "tag": "string",
  • "iv": "string"
}

SearchStatusReasonCode

string (SearchStatusReasonCode)
Enum: "rjct.reference_id.invalid" "rjct.reference_id.duplicate" "rjct.timestamp.invalid" "rjct.search_criteria.invalid" "rjct.filter.invalid" "rjct.sort.invalid" "rjct.pagination.invalid" "rjct.search.too_many_records_found"

Identity verification request status reason codes

"rjct.reference_id.invalid"