ID Repository APIs

This section details about the REST services in ID Repository module.

• ID Services

• VID Services

Identity Services (Private)

These services is used by Registration Processor to store/update during registration process and ID Authentication to retrieve Identity of an Individual for their authentication.

• POST /idrepository/v1/identity/

• GET /idrepository/v1/identity/uin/{uin}?type=bio

• GET /idrepository/v1/identity/rid/{rid}?type=bio

• PATCH /idrepository/v1/identity/

Users of Identity service

1. Registration Processor - Registration Processor will create a new ID record or update an existing ID record in ID repository and store corresponding demographic and bio-metric documents. Registration Processor can also retrieve Identity details of an Individual using RID.

2. ID Authentication - ID Authentication can retrieve Identity details of an Individual using UIN for authentication purpose.

Identity Services does not support search based on attributes of an ID.

POST /idrepository/v1/identity/

This service will create a new ID record in ID repository and store corresponding demographic and bio-metric documents.

Resource URL

https://mosip.io/idrepository/v1/identity/

Resource details

Request Body Parameters

Request

{
  "id": "mosip.id.create",
  "version": "v1",
  "requesttime": "2018-12-11T06:12:25.288Z",
  "request": {
    "registrationId": "12342343200065201812120100555",
    "biometricReferenceId": "<ABIS Reference ID>",
    "identity": {
      "IDSchemaVersion": 1,
      "UIN": 981576026435,
      "fullName": [
        {
          "language": "ara",
          "value": "ابراهيم بن علي"
        },
        {
          "language": "fra",
          "value": "Ibrahim Ibn Ali"
        }
      ],
      "dateOfBirth": "1955/04/15",
      "age": 45,
      "gender": [
        {
          "language": "ara",
          "value": "الذكر"
        },
        {
          "language": "fra",
          "value": "mâle"
        }
      ],
      "addressLine1": [
        {
          "language": "ara",
          "value": "عنوان العينة سطر 1"
        },
        {
          "language": "fra",
          "value": "exemple d'adresse ligne 1"
        }
      ],
      "addressLine2": [
        {
          "language": "ara",
          "value": "عنوان العينة سطر 2"
        },
        {
          "language": "fra",
          "value": "exemple d'adresse ligne 2"
        }
      ],
      "addressLine3": [
        {
          "language": "ara",
          "value": "عنوان العينة سطر 3"
        },
        {
          "language": "fra",
          "value": "exemple d'adresse ligne 3"
        }
      ],
      "region": [
        {
          "language": "ara",
          "value": "طنجة - تطوان - الحسيمة"
        },
        {
          "language": "fra",
          "value": "Tanger-Tétouan-Al Hoceima"
        }
      ],
      "province": [
        {
          "language": "ara",
          "value": "فاس-مكناس"
        },
        {
          "language": "fra",
          "value": "Fès-Meknès"
        }
      ],
      "city": [
        {
          "language": "ara",
          "value": "الدار البيضاء"
        },
        {
          "language": "fra",
          "value": "Casablanca"
        }
      ],
      "postalCode": "570004",
      "phone": "9876543210",
      "email": "[e-mail]",
      "parentOrGuardianRIDOrUIN": 212124324784912,
      "parentOrGuardianName": [
        {
          "language": "ara",
          "value": "سلمى"
        },
        {
          "language": "fra",
          "value": "salma"
        }
      ],
      "proofOfAddress": {
        "format": "pdf",
        "type": "drivingLicense",
        "value": "fileReferenceID"
      },
      "proofOfIdentity": {
        "format": "txt",
        "type": "passport",
        "value": "fileReferenceID"
      },
      "proofOfRelationship": {
        "format": "pdf",
        "type": "passport",
        "value": "fileReferenceID"
      },
      "proofOfDateOfBirth": {
        "format": "pdf",
        "type": "passport",
        "value": "fileReferenceID"
      },
      "individualBiometrics": {
        "format": "cbeff",
        "version": 1,
        "value": "fileReferenceID"
      },
      "parentOrGuardianBiometrics": {
        "format": "cbeff",
        "version": 1,
        "value": "fileReferenceID"
      }
    },
    "documents": [
      {
        "category": "proofOfAddress",
        "value": "<Base 64 encoded byte array of PoA document>"
      },
      {
        "category": "proofOfIdentity",
        "value": "<Base 64 encoded byte array of PoI document>"
      },
      {
        "category": "proofOfRelationship",
        "value": "<Base 64 encoded byte array of PoR document>"
      },
      {
        "category": "individualBiometrics",
        "value": "<Base 64 encoded byte array of CBEFF document>"
      },
      {
        "category": "parentOrGuardianBiometrics",
        "value": "<Base 64 encoded byte array of CBEFF document>"
      }
    ]
  }
}

Responses

Success Response

{
  "id": "mosip.id.create",
  "version": "v1",
  "responsetime": "2018-12-11T06:13:05.218Z",
  "response": {
    "status": "ACTIVATED",
    "entity": "http://mosip.io/idrepository/v1/identity/uin/{uin}"
  }
}

Response Code : 200 (OK)

Failure details

GET /idrepository/v1/identity/uin/{uin}?type=bio

This service will retrieve an ID record from ID repository for a given UIN (Unique Identification Number) and identity type as bio/demo/all.

1. When type=bio is selected, individualBiometrics along with Identity details of the Individual are returned

2. When type=demo is selected, Demographic documents along with Identity details of the Individual are returned

3. When type=all is selected, both individualBiometrics and demographic documents are returned along with Identity details of the Individual

If no identity type is provided, stored Identity details of the Individual will be returned as a default response.

Resource URL

https://mosip.io/idrepository/v1/identity/uin/{uin}?type=bio

Resource details

Responses

Success Response

{
  "id": "mosip.id.read",
  "version": "v1",
  "responsetime": "2018-12-11T06:13:05.218Z",
  "response": {
    //JSON object as per the ID Object Schema defined by the system owner
    "status": "ACTIVATED",
    "identity": {
      "IDSchemaVersion": 1.0,
      "UIN": 981576026435,
      "fullName": [
        {
          "language": "ara",
          "value": "ابراهيم بن علي"
        },
        {
          "language": "fra",
          "value": "Ibrahim Ibn Ali"
        }
      ],
      "dateOfBirth": "1955/04/15",
      "age": 45,
      "gender": [
        {
          "language": "ara",
          "value": "الذكر"
        },
        {
          "language": "fra",
          "value": "mâle"
        }
      ],
      "addressLine1": [
        {
          "language": "ara",
          "value": "عنوان العينة سطر 1"
        },
        {
          "language": "fra",
          "value": "exemple d'adresse ligne 1"
        }
      ],
      "addressLine2": [
        {
          "language": "ara",
          "value": "عنوان العينة سطر 2"
        },
        {
          "language": "fra",
          "value": "exemple d'adresse ligne 2"
        }
      ],
      "addressLine3": [
        {
          "language": "ara",
          "value": "عنوان العينة سطر 3"
        },
        {
          "language": "fra",
          "value": "exemple d'adresse ligne 3"
        }
      ],
      "region": [
        {
          "language": "ara",
          "value": "طنجة - تطوان - الحسيمة"
        },
        {
          "language": "fra",
          "value": "Tanger-Tétouan-Al Hoceima"
        }
      ],
      "province": [
        {
          "language": "ara",
          "value": "فاس-مكناس"
        },
        {
          "language": "fra",
          "value": "Fès-Meknès"
        }
      ],
      "city": [
        {
          "language": "ara",
          "value": "الدار البيضاء"
        },
        {
          "language": "fra",
          "value": "Casablanca"
        }
      ],
      "postalCode": "570004",
      "phone": "9876543210",
      "email": "[e-mail]",
      "parentOrGuardianRIDOrUIN": 212124324784912,
      "parentOrGuardianName": [
        {
          "language": "ara",
          "value": "سلمى"
        },
        {
          "language": "fra",
          "value": "salma"
        }
      ],
      "proofOfAddress": {
        "format": "pdf",
        "type": "drivingLicense",
        "value": "fileReferenceID"
      },
      "proofOfIdentity": {
        "format": "txt",
        "type": "passport",
        "value": "fileReferenceID"
      },
      "proofOfRelationship": {
        "format": "pdf",
        "type": "passport",
        "value": "fileReferenceID"
      },
      "proofOfDateOfBirth": {
        "format": "pdf",
        "type": "passport",
        "value": "fileReferenceID"
      },
      "individualBiometrics": {
        "format": "cbeff",
        "version": 1.0,
        "value": "fileReferenceID"
      },
      "parentOrGuardianBiometrics": {
        "format": "cbeff",
        "version": 1.0,
        "value": "fileReferenceID"
      }
    },
    "documents": [
      {
        "category": "individualBiometrics",
        "value": "<Base 64 encoded byte array of CBEFF document>"
      }
    ]
  }
}

Response Code : 200 (OK)

Failure details

GET /idrepository/v1/identity/rid/{rid}?type=bio

This operation will retrieve an ID record from ID repository for a given RID (Registration ID) and identity type as bio/demo/all.

1. When type=bio is selected, individualBiometrics along with Identity details of Individual are returned

2. When type=demo is selected, Demographic documents along with Identity details of Individual are returned

3. When type=all is selected, both individualBiometrics and demographic documents are returned along with Identity details of Individual

If no identity type is provided, stored latest Identity details of Individual mapped to the UIN of input RID will be returned as a default response.

Resource URL

https://mosip.io/idrepository/v1/identity/rid/{rid}?type=bio

Resource details

Responses

Success Response

{
  "id": "mosip.id.read",
  "version": "v1",
  "responsetime": "2018-12-11T06:13:05.218Z",
  "response": {
    //JSON object as per the ID Object Schema defined by the system owner
    "status": "ACTIVATED",
    "identity": {
      "IDSchemaVersion": 1.0,
      "UIN": 981576026435,
      "fullName": [
        {
          "language": "ara",
          "value": "ابراهيم بن علي"
        },
        {
          "language": "fra",
          "value": "Ibrahim Ibn Ali"
        }
      ],
      "dateOfBirth": "1955/04/15",
      "age": 45,
      "gender": [
        {
          "language": "ara",
          "value": "الذكر"
        },
        {
          "language": "fra",
          "value": "mâle"
        }
      ],
      "addressLine1": [
        {
          "language": "ara",
          "value": "عنوان العينة سطر 1"
        },
        {
          "language": "fra",
          "value": "exemple d'adresse ligne 1"
        }
      ],
      "addressLine2": [
        {
          "language": "ara",
          "value": "عنوان العينة سطر 2"
        },
        {
          "language": "fra",
          "value": "exemple d'adresse ligne 2"
        }
      ],
      "addressLine3": [
        {
          "language": "ara",
          "value": "عنوان العينة سطر 3"
        },
        {
          "language": "fra",
          "value": "exemple d'adresse ligne 3"
        }
      ],
      "region": [
        {
          "language": "ara",
          "value": "طنجة - تطوان - الحسيمة"
        },
        {
          "language": "fra",
          "value": "Tanger-Tétouan-Al Hoceima"
        }
      ],
      "province": [
        {
          "language": "ara",
          "value": "فاس-مكناس"
        },
        {
          "language": "fra",
          "value": "Fès-Meknès"
        }
      ],
      "city": [
        {
          "language": "ara",
          "value": "الدار البيضاء"
        },
        {
          "language": "fra",
          "value": "Casablanca"
        }
      ],
      "postalCode": "570004",
      "phone": "9876543210",
      "email": "[e-mail]",
      "parentOrGuardianRIDOrUIN": 212124324784912,
      "parentOrGuardianName": [
        {
          "language": "ara",
          "value": "سلمى"
        },
        {
          "language": "fra",
          "value": "salma"
        }
      ],
      "proofOfAddress": {
        "format": "pdf",
        "type": "drivingLicense",
        "value": "fileReferenceID"
      },
      "proofOfIdentity": {
        "format": "txt",
        "type": "passport",
        "value": "fileReferenceID"
      },
      "proofOfRelationship": {
        "format": "pdf",
        "type": "passport",
        "value": "fileReferenceID"
      },
      "proofOfDateOfBirth": {
        "format": "pdf",
        "type": "passport",
        "value": "fileReferenceID"
      },
      "individualBiometrics": {
        "format": "cbeff",
        "version": 1.0,
        "value": "fileReferenceID"
      },
      "parentOrGuardianBiometrics": {
        "format": "cbeff",
        "version": 1.0,
        "value": "fileReferenceID"
      }
    },
    "documents": [
      {
        "category": "individualBiometrics",
        "value": "<Base 64 encoded byte array of CBEFF document>"
      }
    ]
  }
}

Response Code : 200 (OK)

Failure details

PATCH /idrepository/v1/identity/

This operation will update an existing ID record in the ID repository for a given UIN (Unique Identification Number)

Resource URL

https://mosip.io/idrepository/v1/identity/

Resource details

Request Body Parameters

Request

{
  "id": "mosip.id.update",
  "version": "v1",
  "requesttime": "2018-12-11T06:12:25.288Z",
  "request": {
    //JSON object as per the ID Object Schema defined by the system owner
    "registrationId": "12342343200065201812120100556",
    "biometricReferenceId": "<ABIS Reference ID>",
    "status": "DEACTIVATED",
    "identity": {
      "UIN": 981576026435,
      "email": "[e-mail]",
      "individualBiometrics": {
        "format": "cbeff",
        "version": 1.0,
        "value": "updated_bio_doc_name"
      }
    },
    "documents": [
      {
        "category": "individualBiometrics",
        "value": "<Base 64 encoded byte array of updated CBEFF document>"
      }
    ]
  }
}

Responses

Success Response

{
  "id": "mosip.id.update",
  "version": "v1",
  "responsetime": "2018-12-11T06:13:05.218Z",
  "response": {
    "status": "DEACTIVATED",
    "entity": "http://mosip.io/identity/568469473107"
  }
}

Response Code : 200 (OK)

Failure details

VID Services (Private)

These services can be used to perform various operations on VID like generate or re-generate VID, update VID status, etc.

• POST /idrepository/v1/vid

• GET /idrepository/v1/vid/{vid}

• PATCH /idrepository/v1/vid/{vid}

• POST /idrepository/v1/vid/{vid}/regenerate

• PATCH /idrepository/v2/vid/deactivate

• PATCH /idrepository/v2/vid/reactivate

Users of VID services

1. Registration Processor - Registration Processor will create a new perpetual VID once UIN is generated successfully.

2. Resident Services - Individual can use Resident Services to generate or re-generate a new temporary VID.

3. ID Authentication - ID Authentication can retrieve UIN for a given VID for authenticating Individual using VID.

POST /idrepository/v1/vid

This service will generate a new VID based on VID type provided.

Resource URL

https://mosip.io/idrepository/v1/vid

Resource details

Request Body Parameters

Request

{
  "id": "mosip.vid.create",
  "version": "v1",
  "requesttime": "2019-04-30T06:12:25.288Z",
  "request": {
    "vidType": "Perpetual",
    "UIN": 981576026435
  }
}

Responses

Success Response

{
  "id": "mosip.vid.create",
  "version": "v1",
  "responsetime": "2019-04-30T06:13:05.218Z",
  "response": {
    "vidStatus": "ACTIVE",
    "VID": 1234512345
  }
}

Response Code : 200 (OK)

Failure details

GET /idrepository/v1/vid/{vid}

This service will retrieve associated decrypted UIN for a given VID, once VID is successfully validated.

Resource URL

https://mosip.io/idrepository/v1/vid/{vid}

Resource details

Responses

Success Response

{
  "id": "mosip.vid.read",
  "version": "v1",
  "responsetime": "2019-04-30T06:13:05.218Z",
  "response": {
    "UIN": 981576026435
  }
}

Response Code : 200 (OK)

Failure details

PATCH /idrepository/v1/vid/{vid}

This service will update status associated with a given VID, if the current status of VID is 'ACTIVE'.

Resource URL

https://mosip.io/idrepository/v1/vid/{vid}

Resource details

Request Body Parameters

Request

{
  "id": "mosip.vid.update",
  "version": "v1",
  "requesttime": "2019-04-30T06:12:25.288Z",
  "request": {
    "vidStatus": 'REVOKED'
  }
}

Responses

Success Response

{
  "id": "mosip.vid.update",
  "version": "v1",
  "responsetime": "2019-04-30T06:13:05.218Z",
  "response": {
    "vidStatus": "REVOKED",
    "UIN": null,
    "VID": null,
    "restoredVidDetails": {
      "vidStatus": "ACTIVE",
      "UIN": null,
      "VID": 4290754956350965
    }
  }
}

Response Code : 200 (OK)

Failure details

POST /idrepository/v1/vid/{vid}/regenerate

This service will re-generate VID for a given VID, only if the current status of VID is 'ACTIVE', 'USED', or 'EXPIRED'.

Resource URL

https://mosip.io/idrepository/v1/vid/{vid}/regenerate

Resource details

Responses

Success Response

{
  "id": "mosip.vid.regenerate",
  "version": "v1",
  "responsetime": "2019-05-21T06:13:05.218Z",
  "response": {
    "vidStatus": 'ACTIVE',
    "VID": 1234512345
  }
}

Response Code : 200 (OK)

Failure details

PATCH /idrepository/v2/vid/deactivate

This service will de-activate VIDs mapped against the provided UIN, only if the current status of VID is 'ACTIVE'.

Resource URL

https://mosip.io/idrepository/v2/vid/deactivate

Resource details

Request Body Parameters

Request

{
  "id": "mosip.vid.deactivate",
  "version": "v2",
  "requesttime": "2019-05-21T06:13:05.218Z",
  "request": {
    "UIN": 981576026435
  }
}

Responses

Success Response

{
  "id": "mosip.vid.deactivate",
  "version": "v2",
  "responsetime": "2019-05-21T06:13:05.218Z",
  "response": {
    "vidStatus": 'DEACTIVATED'
  }
}

Response Code : 200 (OK)

Failure details

PATCH /idrepository/v2/vid/reactivate

This service will re-activate VIDs mapped against the provided UIN, only if the current status of VID is 'DEACTIVATED', 'INACTIVE' and not 'EXPIRED'.

Resource URL

https://mosip.io/idrepository/v2/vid/reactivate

Resource details

Request Body Parameters

Request

{
  "id": "mosip.vid.reactivate",
  "version": "v2",
  "requesttime": "2019-05-21T06:13:05.218Z",
  "request": {
    "UIN": 981576026435
  }
}

Responses

Success Response

{
  "id": "mosip.vid.reactivate",
  "version": "v2",
  "responsetime": "2019-05-21T06:13:05.218Z",
  "response": {
    "vidStatus": ‘ACTIVE’
  }
}

Response Code : 200 (OK)

Failure details

Authentication Types Status Service (Internal)

Authentication Types Status Service can be used by Resident Services to retrieve or update status (locked or unlocked) of Auth Types of an Individual using VID/UIN.

Users of Retrieve Authentication Types Status Service -

1. Resident Services - Individual can request to lock or unlock one or more authentication types using Resident Services, which in turn calls this service to store or retrieve the auth type status.

GET /idauthentication/v1/internal/authtypes/status/individualIdType/:IDType/individualId/:ID

This request will retrieve status (locked or unlocked) of Auth Types of an Individual using VID/UIN.

Resource URL

https://{base_url}/idauthentication/v1/internal/authtypes/status/individualIdType/:IDType/individualId/:ID

Resource details

Request Path Parameters

Responses

Success Response

Response Code : 200 (OK)

{
  "id": "mosip.identity.authtype.status.read",
  "version": "1.0",
  "requestTime": "2019-02-15T10:01:57.086+05:30",
  "individualId": "9830872690593682",
  "individualIdType": "VID",
  "request": {
    // Status of AuthTypes and AuthSubTypes
    "authTypes": [
      {
        "authType": "otp",
        "isLocked": false
      },
      {
        "authType": "demo",
        "isLocked": false
      },
      {
        "authType": "bio",
        "authSubType": "Finger",
        "isLocked": true
      },
      {
        "authType": "bio",
        "authSubType": "Iris",
        "isLocked": true
      },
      {
        "authType": "bio",
        "authSubType": "Face",
        "isLocked": true
      }
    ]
  }
}

Failed Response

Response Code : 200 (OK)

{
  //API Metadata
  "id": "mosip.identity.authtype.status.read",
  "version": "v1",
  "responseTime": "2019-02-15T07:23:19.590+05:30",
  "errors": [
    {
      "errorCode": "IDA-MLC-002",
      "errorMessage": "Invalid UIN",
      "actionMessage": "Please retry with the correct UIN"
    }
  ]
}

Failure Details

PUT /idauthentication/v1/internal/authtypes/status

This request will lock or unlock one or more authenticate types for an Individual using VID/UIN.

Resource URL

https://{base_url}/idauthentication/v1/internal/authtypes/status

Resource details

Request Body Parameters

Request Body

{
  "id": "mosip.identity.authtype.status.update",
  "version": "1.0",
  "requestTime": "2019-02-15T10:01:57.086+05:30",
  "consentObtained": true,
  "individualId": "9830872690593682",
  "individualIdType": "VID",
  "request": {
    // AuthTypes and AuthSubTypes present in the below list can be locked or unlocked
    "authTypes": [
      {
        "authType": "otp",
        "isLocked": false
      },
      {
        "authType": "demo",
        "isLocked": false
      },
      {
        "authType": "bio",
        "authSubType": "Finger",
        "isLocked": true
      },
      {
        "authType": "bio",
        "authSubType": "Iris",
        "isLocked": true
      },
      {
        "authType": "bio",
        "authSubType": "Face",
        "isLocked": true
      }
    ]
  }
}

Responses

Success Response

Response Code : 200 (OK)

{
  //API Metadata
  "id": "mosip.identity.authtype.status.update",
  "version": "1.0",
  "responseTime": "2019-02-15T07:23:19.590+05:30",
  "errors": null
}

Failed Response

Response Code : 200 (OK)

{
  //API Metadata
  "id": "mosip.identity.authtype.status.update",
  "version": "v1",
  "responseTime": "2019-02-15T07:23:19.590+05:30",
  "errors": [
    {
      "errorCode": "IDA-MLC-002",
      "errorMessage": "Invalid UIN",
      "actionMessage": "Please retry with the correct UIN"
    }
  ]
}

Failure Details