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:

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

Sync

Sync endpoints

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

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": {
    }
}

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"