Access the data in a DCS response

When you make a successful request to the Document Checking Service (DCS), the DCS will respond with:

• a 200 HTTP response code
• a secured JSON object with data you requested

Follow these instructions to access the data in the DCS response. You’ll need to:

1. Retrieve the response body.
2. Validate the outer signature.
3. Decrypt the JSON Web Encryption (JWE) object inside.
4. Validate the inner signature to reveal the JSON message inside.

You can read about the data contained in JSON messages in the API reference section.

Prerequisites for accessing the data in a DCS response

You should have successfully submitted a request to the DCS which returns a 200 HTTP response code.

You’ll need to use a library to work with the JSON Web Signature (JWS) and JSON Web Encryption (JWE) objects. You can use the same one you used to sign and encrypt your DCS request.

You’ll need:

• your encryption private key
• to download the DCS public signing certificate

Retrieve the response body

Extract the response body from the DCS response and consume it using your JWS library. You must extract the response body in a form your JWS library can consume - this is likely to be a string.

An example response string is:

eyJhbGciOiJSUzI1NiJ9.ZXlKaGJHY2lPaUpTVTBFdFQwRkZVQzB5TlRZaUxDSmxibU1pT2lKQk1USTRRMEpETFVoVE1qVTJJaXdpZEhsd0lqb2lTbGRGSW4wLk5POFVpZ3p5Vl85dUV6Yi1uQUFXeENsZTFhRno0eVpWNVBQcUt2dnlydkdudDJFdjdudGxzZHY3Vkd0SGJ1UHdqdE96d25qdC1hRHhablpMcmc5aVhEbmRiRUNFZldwUTR6bXVFQkphdy0xb2hYVTFWWmlhVjZoZ0VIVmlDX3dFblJsbUlZSjJlWTZiQzQ1NEVzMGRxNEtaY3hnRTN1ZkRYdHYyX3lnbFpfUjNqUEFCNFhxY1Qyb1lKMUtrNjczLWxfbmtNS2tJX2pvbXZTcGtzN1ByNENJTWRDS2FUd2V4V1FTUVBPeVIxWm05ZnFlc3d4aEEzYjRWTEVILXZpOGRGRks4aExqOGo0akpOVW1NVHRHb2FNbGVranFEN052RWdWLUFYbVp5d296S0VQazRrZkYwbXpaUm1CeG5zdmJscjUtZ2tJOHE3OUNNMzdzellqVHRnUS5mSFFiU0xUd1JwdjJPa1dkNG5abGdBLkI2Mnh3eVJ5MlVEdW02T2VZZXd6MWhDVWk2OW9jaEdGM3NuR195aWhDMUROaDNfdU9vRW1Leks1WHhnRlc4Q1FyWHpIaktxeWRtc2hKcFBwS0M4d3Y2THhrR2hYN1JQY2JpQ0s1NnhBZ0V6blJkZGV2SWFtQkhoYUZiWEJGMXJoN2lnanRjdTJ1YVRKLURTY1FESTlFOG1NLVVYcTJkZk1RR0tvYllZRk5mOVVOck5xWXV5RFF4Z3I4RFVOM0l0MTAtbFF4eUpSTHVBQmEydklfR2Z1dVM2Y2dMV2FIRGY0TjAtencwMWxXNS02R0ZFeDVuTDc3TEtoX1czNC1TWG5xTkNzSU9YdnN2WkRDYnhJZ2ZDTE9zYW5NbmwtcXUwVEJpbDE0TE1XMDNyS2s5MEJTdUd3SEdRY1l6VTZRck9yUDROY1dPR294cXRFdFBobVR0RW8wek5WWjFKT0lGVmpsSVpjcExYeGxqLXJQdHllUV9VMXVzZkJOa2h4VzBCVTFuNG82RkZUUndUS2VFTGpCbi1HS2JQVlMzS0x0ckE5SDRDWTlveHFGbnA1bDJqOEEySnc1ZU1FZi0zOVJaYVctVVVTN0d0Z0FJS1lTUUhUdW9fTUpmV3VPVTN6cC1nNWd6Y1Y4WGNJOVhieG5LdjU1OWxvQkhBenRWNV9BV195SS13NjUzSVpHV0NuRC0zcUdUY2diODl2TldhQlhmSlJNWTBtUVJpaUxBVVVOelhITk15QXk0SnA1Q1pKRVpjTVBfRHYtNXdvd3YyNlN2aTNOcm1sRTB1eUQ2RHpkYUVndmhxdDdOZVVzOUowY3hrRXY0azVjS0FVeU1najlCTEpYT0tUcWloeEI1Mk8ydEI5ZHVmUGlzemk2R1JERmRtb2hLQnYwOHlLa1c3WVNmNVBtX2FHX2p1ek9MQWx6bW9ZWm5rWmpzVk9HUVBHamFMNTRLV3Zady4waVg2c2MzcWNCNENWNklBR09VTDd3.TR50Vggrkin5ccopyUQ5T5U04ViIIM5RTDyhVBLN62UTu3N1xxi7gQyufiPVbO3cyIfH9KznPZ_JxRfIsCQNyKwx0II61hpAXIZHMGBhadiFAwYQEvB0l8Iwxf7nvQw-d5blPz0cVNc04z6iNUImbSDGB1LgJKRNBsgcd4CZYWFH9ipAVtqNmj1LYasWIcn8y-OIRCHbQ_wySXQxc-zyckVLT0u50jqAuhRhEFx1luuOkHBac0wFJPvRq24ntY0va8xi-xHgjbJuvI8xv7IpYpYcUUqDErFQbWiEpGo0VAbc9UXlZ-DiE_B9mYf7bNvdgq4zxmULMHXpvnPc-3TvkQ

This string is a compact JSON Web Token representation. It is delimited into 3 sections by ‘.’ (a period). For more information on JWS Compact Serialization see RFC7515.

Validate the outer signature

Validating the outer signature means you’re removing the first layer of encryption.

To validate the outer signature, you must:

1. Use your JWS library’s signature validation method.
2. Pass your JWS library the DCS response body string.
3. Pass your JWS library the DCS public signing certificate.

This will return a string which is the response body string with the signature removed. Keep this for the next step.

Assuming your library returns compact tokens, an example of the returned string is:

eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwidHlwIjoiSldFIn0.NO8UigzyV_9uEzb-nAAWxCle1aFz4yZV5PPqKvvyrvGnt2Ev7ntlsdv7VGtHbuPwjtOzwnjt-aDxZnZLrg9iXDndbECEfWpQ4zmuEBJaw-1ohXU1VZiaV6hgEHViC_wEnRlmIYJ2eY6bC454Es0dq4KZcxgE3ufDXtv2_yglZ_R3jPAB4XqcT2oYJ1Kk673-l_nkMKkI_jomvSpks7Pr4CIMdCKaTwexWQSQPOyR1Zm9fqeswxhA3b4VLEH-vi8dFFK8hLj8j4jJNUmMTtGoaMlekjqD7NvEgV-AXmZywozKEPk4kfF0mzZRmBxnsvblr5-gkI8q79CM37szYjTtgQ.fHQbSLTwRpv2OkWd4nZlgA.B62xwyRy2UDum6OeYewz1hCUi69ochGF3snG_yihC1DNh3_uOoEmKzK5XxgFW8CQrXzHjKqydmshJpPpKC8wv6LxkGhX7RPcbiCK56xAgEznRddevIamBHhaFbXBF1rh7igjtcu2uaTJ-DScQDI9E8mM-UXq2dfMQGKobYYFNf9UNrNqYuyDQxgr8DUN3It10-lQxyJRLuABa2vI_GfuuS6cgLWaHDf4N0-zw01lW5-6GFEx5nL77LKh_W34-SXnqNCsIOXvsvZDCbxIgfCLOsanMnl-qu0TBil14LMW03rKk90BSuGwHGQcYzU6QrOrP4NcWOGoxqtEtPhmTtEo0zNVZ1JOIFVjlIZcpLXxlj-rPtyeQ_U1usfBNkhxW0BU1n4o6FFTRwTKeELjBn-GKbPVS3KLtrA9H4CY9oxqFnp5l2j8A2Jw5eMEf-39RZaW-UUS7GtgAIKYSQHTuo_MJfWuOU3zp-g5gzcV8XcI9XbxnKv559loBHAztV5_AW_yI-w653IZGWCnD-3qGTcgb89vNWaBXfJRMY0mQRiiLAUUNzXHNMyAy4Jp5CZJEZcMP_Dv-5wowv26Svi3NrmlE0uyD6DzdaEgvhqt7NeUs9J0cxkEv4k5cKAUyMgj9BLJXOKTqihxB52O2tB9dufPiszi6GRDFdmohKBv08yKkW7YSf5Pm_aG_juzOLAlzmoYZnkZjsVOGQPGjaL54KWvZw.0iX6sc3qcB4CV6IAGOUL7w

Decrypt the string

To decrypt the string, you must:

1. Use your JWE library’s decryption method.
2. Pass your decryption method the DCS response body string with the signature removed, which you generated in the previous step.
3. Pass your decryption method your encryption private key.

The method will return the JSON payload.

Assuming your library returns compact tokens, an example of the returned string is:

eyJhbGciOiJSUzI1NiJ9.eyJjb3JyZWxhdGlvbklkIjoiNTc4MmQ1MWItNWI3Mi00NDQ4LThiMDYtY2Q4NmM0NDZiYzljIiwiZXJyb3IiOmZhbHNlLCJyZXF1ZXN0SWQiOiJiNWUyY2FjNi0zM2M4LTQ2NjQtYjFmZS0yYjQ5MGZkYjFjODIiLCJ2YWxpZCI6dHJ1ZX0.Me6ZAywbIrWZ7h0ekrCFxnhYDXdOmSWQLhQiuKq0msVtd5oQLzBGVWSs3agj9mQBN3yszYm6aFABc8r93t5jidaNCyaUJJSXd0qfQoK7G4eJaxEnOzSS26oRqk8t6OYtcfTfQ3QrZsS64B7OH0AhYR76RIeVWrVLbQ3qMsFujMqYZ68A6mDbeGYIUf9Wow41urbFHVbFoP30CA86Mb-JyA53nydaiBA5glppC571Ic-RUNF4HordP2i2c3X8lKkUmWlExormra4cXNEzDnaEbrRRTMSwcixTkpMWvDIN_7kqS2v9M84xBWDzxdnfS5F0UFgUDMWrrbk_dI_pQp1LgA

Validate the inner signature

Validating the inner signature means you’re removing the final layer of encryption.

To validate the inner signature, you must:

1. Use your JWS library.
2. Pass your JWS library the decrypted string you generated in the previous step.
3. Pass your JWS library the DCS public signing certificate.

You’ll get a JSON object containing the passport information you requested from DCS.

An example of the returned JSON string is:

{"correlationId":"12345678-abcd-ef01-2345-6789abcdef01","error":false,"requestId":"87654321-abcd-ef01-2345-6789abcdef01","valid":true}

Review and use the human-readable response

You now have a plain text JSON object for your application to use. Read the object to discover whether:

• the passport was valid (valid: true)
• the passport was invalid (valid: false)
• an error occurred from Her Majesty’s Passport Office (error: true)

You can read further guidance about what responses mean when making a DCS check.

This page was last reviewed on 19 October 2020.