Digital Convergence Initiative
API docs by Redocly

Interoperability APIs - Integrated Beneficiary Registry (1.0.0)

Download OpenAPI specification:Download

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

The IBR(Integrated Beneficiary Registry) interoperability APIs describes different APIs some of them are usecase specific and other are generalized APIs to perform interoperable operations between IBR registry 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. Enrollment updates: The enrollment updates API send details of beneficiaries enrolled in programs from SP-System
  3. Enrolled : the enrolled API is a special type of search to return the programs a beneficiary is enrolled in

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/txn/status

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

Authorizations:
None
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 SP-System. The response with information about request and in some case it may contain data as well.

Authorizations:
None
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/enrollment/updates

The /registry/enrollments/updates endpoint will be implemented by IBR to receive details of beneficiaries enrolled in programs from SP-System. The receipt_type and beneficiaries will be required to make request. Three receipt types are supported as of now, they are

  1. Enrolled beneficiaries
  2. Updated beneficiaries details The beneficiaries will contain list of beneficiaries information for which enrollments updated to be generated.
Authorizations:
None
Request Body schema:
required
signature
string (MsgSignature)

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

required
object

Message header

EnrollmentUpdatesRequest (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/sync/enrolled

search programmes person is enrolled in

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

/registry/sync/txn/status

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

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 enable 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": [
    ]
}

EnrollmentUpdatesRequest

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. Enrolled beneficiaries - It return the beneficiaries enrolled into system.
  2. Updated beneficiaries - If return updated status
{
  • "transaction_id": 123456789,
  • "enrolled_updates": {
    }
}

EnrollmentUpdatesResponse

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",
  • "enrolled_response": [
    ]
}

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": 123456789,
  • "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
  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"