Digital Convergence Initiative
API docs by Redocly

Interoperability APIs - Foundational/Functional registries (1.0.0)

Download OpenAPI specification:Download

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

The Farmer registry interoperability APIs describes different APIs some of them are usecase specific and other are generalized APIs to perform interoperable operations between Farmer 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. Event subscription: The Event subscription APIs describe APIs useful to subscribe / unsubscribe events. When any event happens in farmer 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

Async

Async endpoints

/registry/subscribe

Subscribe to a life 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 contaion 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
{
  • "errors": [
    ]
}

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

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

/registry/txn/status

The /registry/txn/status will be implemented by FR. 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 SP-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
{
  • "errors": [
    ]
}

Sync

Sync endpoints

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

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 (SubscriptionCode) [ 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": [
    ]
}

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"

SubscribeStatusReasonCode

string (SubscribeStatusReasonCode)
Enum: "rjct.reference_id.invalid" "rjct.reference_id.duplicate" "rjct.timestamp.invalid" "rjct.notify_types.invalid" "rjct.notify_details.invalid" "rjct.person_id.invalid" "rjct.event.already_subscribed"

Identity verification request status reason codes

"rjct.reference_id.invalid"

UnSubscribeStatusReasonCode

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

"rjct.reference_id.invalid"