Digital Convergence Initiative
API docs by Redocly

Interoperability APIs - Social Registry

Download OpenAPI specification:Download

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

The Social Registry interoperability APIs describes different APIs some of them are usecase specific and other are generalized APIs to perform interoperable operations between social registry and SPMIS. 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. Event subscription: The Event subscription APIs describe APIs useful to subscribe / unsubscribe events. When any event happens in crvs registry it sends event details on notify end point
  3. Request status check: The request status checking APIs implement to check status of request sent in any above APIs

Gitbook reference link :

Code directory links:

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.
  • Refere 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" version: 1.0.0

Async

Async endpoints

/registry/subscribe

The /registry/subscribe end point tobe implemented by SR to receive subscription request from SPMIS. The subscription request contain event type, frequency and query information, based on that resistry will send notification to subscriber.

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 contaion query with frequency and other info on which notification to be sent by registry to subscriber, The IBR supports benefit_disbusrement,programme_exited events as of now

Responses

Request samples

Content type
{
  • "signature": "Signature: namespace=\"g2p\", 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
{
  • "errors": [
    ]
}

/registry/on-subscribe

The /registry/on-subscribe request tobe implemented by SPMIS to receive subscription response from SR. The response with contain subscription code which to be used to unsubscribe the subscription or to track subscription details.

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=\"g2p\", 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
{
  • "errors": [
    ]
}

/registry/unsubscribe

The /registry/unsubscribe endpoint will be implemented by SR, SPMIS can send request to unsubscribe existing subscription(s) by subscription_code(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
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=\"g2p\", 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
{
  • "errors": [
    ]
}

/registry/on-unsubscribe

The /registry/on-unsubscribe will be implemented by SPMIS to receive unsubscribe response from SR. It will contain status information of unsubscribe request.

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=\"g2p\", 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
{
  • "errors": [
    ]
}

/registry/notify

The /registry/sync/notify end point will be implemented by SPMIS to receive notification for subscribed event. The notification will be sent based on subscription criteria.

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=\"g2p\", 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
{
  • "errors": [
    ]
}

/registry/on-notify

The /registry/on-notify will be implemented by SR to receive notification response from SPMIS.

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

ReceiptResponse (object) or EncryptedMessage (object)

Responses

Request samples

Content type
{
  • "signature": "Signature: namespace=\"g2p\", 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
{
  • "errors": [
    ]
}

/registry/txn/status

The /registry/txn/status will be implemented by SR. 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=\"g2p\", 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
{
  • "errors": [
    ]
}

/registry/txn/on-status

The /registry/txn/on-status will be implemented by SPMIS. 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=\"g2p\", 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
{
  • "errors": [
    ]
}

Sync

Sync endpoints

/registry/sync/notify

The /registry/sync/notify end point will be implemented by SPMIS to receive notification for subscribed event. The notification will be sent based on subscription criteria.

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=\"g2p\", 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
{
  • "errors": [
    ]
}

/registry/sync/txn/status

The /registry/sync/txn/status will be implemented by SR. This will check status of reach request using transaction_id and/or reference_id(s).

Authorizations:
Authorization
Request Body schema: application/json
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
application/json
{
  • "signature": "Signature: namespace=\"g2p\", 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
{
  • "errors": [
    ]
}

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 enabel multiple individual requests with respective consent/authorize codes
{
  • "transaction_id": 123456789,
  • "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
  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": 123456789,
  • "correlation_id": "9876543210",
  • "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": 123456789,
  • "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
  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": 123456789,
  • "correlation_id": "9876543210",
  • "subscribe_response": [
    ]
}

ReceiptRequest

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

Receipt information contains receipt type and list of beneficiaries

  1. Register - It indicates that beneficiary have registered into system.
  2. Deregister - If receipt is for a programme exit then programm information with suspended date to be recorded
{
  • "transaction_id": 123456789,
  • "receipt_information": {
    }
}

ReceiptResponse

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

Receipt information contains receipt type and list of beneficiaries

  1. Register - It indicates that beneficiary have registered into system.
  2. Deregister - If receipt is for a programme exit then programm information with suspended date to be recorded
{
  • "transaction_id": 123456789,
  • "receipt_information": {
    }
}

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": 123456789,
  • "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
  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": 123456789,
  • "correlation_id": "9876543210",
  • "txnstatus_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": 123456789,
  • "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)
timesstamp
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
Array of strings[ items <= 99 characters ]
{
  • "transaction_id": 123456789,
  • "timesstamp": "",
  • "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
  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)
timesatmp
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": 123456789,
  • "correlation_id": "9876543210",
  • "timesatmp": "",
  • "status": "rcvd",
  • "status_reason_code": "rjct.reference_id.invalid",
  • "status_reason_message": "string",
  • "subscription_status": [
    ]
}

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"