How to add an identification document to a customer record

In this tutorial, you'll learn how to

Update a COS customer record with physical ID metadata or other identification information.

The tutorial uses these API endpoints

API	Description
POST /core/v1/cm/customers/{id}/identifications	Adds unique identification metadata of customer-identifying documents to customer details.

Before you begin

Make sure you have:

• API credentials

• Customer ID (only available once the customer is added to COS)

• The necessary details for the identification you are adding to the customer record. Depending on the type of identification, you might need:

  • ID serial number

  • Expiration date

  • Details of the issuing authority

  • Other information

Add identification information to an existing customer

You might want or need to add a drivers license, passport or other identification to a customer record. If your agreement with CR includes credit BIN sponsorship, you need to add the card processor unique identifier for that customer to their COS record.

In this tutorial, you'll add a driver's license to Peter Griffin's customer record.

a. To add identification information

1. Call POST /core/v1/cm/customers/{id}/identifications. The attributes below are required. A full list of attributes is found here.

   Detail	Request attribute name	Value to use in the request
   CR customer ID (provided when the customer was onboarded to COS)	customerId	Use the ID from the Onboard a customer tutorial
   True if the ID is the primary ID for this customer. Otherwise false.	isPrimary	true
   License ID number	idNumber	123 456 789
   ID type	idType	DriversLicense
   License Issue date	issuedDate	2022-07-15
   License Expiration date	expDate	2029-07-14
   License Issuing authority	issuingAuthority	New York DMV
   License Issuing country code	issuingCountryCode	US

   Important

   We highly recommend you include an idempotency key in your request header to provide duplicate protection in the event of a failure. Read more about idempotency keys here.

   Copy

   Sample request for POST /core/v1/cm/customers/{id}/identification

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   curl -X POST
   --header 'Content-Type: application/json'
   --header 'Accept: application/json'
   --header 'Authorization: Bearer <token>'
   -d '{ \
     "isPrimary": true,
     "idNumber": "123 456 789",
     "idType": "DriversLicense",
     "issuedDate": "2022-07-15",
     "expDate": "2029-07-14",
     "verifiedDate": "2023-05-21",
     "issuingAuthority": "NY DMV",
     "issuingStateOrProvince": "NY",
     "issuingCountryCode": "US",
   }' 'https://sandbox.crbcos.com/Core/v1/cm/customers/b71cf966-7896-40a0-88c5-af5g0138fc8c/identifications'

2. A successful API call returns a JSON response confirming the identification details added in COS. The id attribute indicates the COS ID of that specific identification item. In the sample below, the ID is 6d3add34-0a1e-4a4e-9c7f-b00a0091e308. Yours will be different.

3. Copy

   Response sample

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   {
     "id": "6d3add34-0a1e-4a4e-9c7f-b00a0091e308",
     "customerId": "b71cf966-7896-40a0-88c5-af5g0138fc8c",
     "isPrimary": true,
     "idNumber": "123 456 789",
     "status": "Active",
     "idType": "DriversLicense",
     "issuedDate": "2022-07-15",
     "expDate": "2029-07-14",
     "issuingAuthority": "NY DMV",
     "issuingStateOrProvince": "NY",
     "issuingCountryCode": "US",
     "createdAt": "2023-05-22T04:51:09.4656083-04:00",
     "lastModifiedAt": "2023-05-22T04:51:09.4656083-04:00",
     "partnerId": "cd9c12f4-7691-424a-b38b-af5b0134c611"
   }