Applications

List KYC Applications

List KYC applications visible to the authorized User or Application.

curl -i \
     -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7fSwiZXhwIjpudWxsLCJpYXQiOjE1NTk4Nzg1NzQsImp0aSI6IjYzYTJkY2QzLWI5OTgtNDZjNC1hNzFkLTQ5MjU4YTBhYmEyMyIsInN1YiI6ImFwcGxpY2F0aW9uOmNiMjAzN2Y3LTc5ZmMtNDBmNC05NzIwLWFkYTYzNmRhNDE4MyJ9.NQLm__LbMWor-9GMG0LPcH4yQIbu9Uw70kJfRt1KP64' \
     https://bookie.provide.services/api/v1/kyc_applications
     HTTP/2 200
     
     date: Wed, 12 Jun 2019 05:39:19 GMT
     content-type: application/json; charset=UTF-8
     access-control-allow-credentials: true
     access-control-allow-headers: Accept, Accept-Encoding, Authorization, Cache-Control, Content-Length, Content-Type, Origin, User-Agent, X-CSRF-Token, X-Requested-Withaccess-control-allow-methods: GET, POST, PUT, DELETE, OPTIONS
     access-control-allow-origin: *
     access-control-expose-headers: X-Total-Results-Count
     x-total-results-count: 3

Response JSON:

[
  {
    "id":"72258a99-1518-4526-a5fa-043081eee7f0",
    "created_at":"2019-06-12T02:31:33.613098-04:00",
    "application_id":"bca2348c-442f-4c48-99a4-7b3510385e53",
    "user_id":"47069619-2035-4193-bdd0-af4d5096b649",
    "provider":"identitymind",
    "identifier":null,
    "type":"kyc",
    "status":"failed",
    "name":"Tim Evans",
    "description":"No national id country specified, and invalid format for US Social Security Number"
  },
  {
    "id":"13bd0b24-f0d9-4caa-89ab-259c058877ce",
    "created_at":"2019-11-13T03:55:02.687098-05:00",
    "application_id":"dc4152f7-456f-41ed-96b4-e52b8faa05fd",
    "user_id":"9a253758-197a-4308-8d2d-61cfe9317644",
    "provider":"vouched",
    "identifier":"OsccQPWf",
    "type":"kyc",
    "status":"remediate",
    "name":"John Smith",
    "description":null
  },
  {
    "id":"e40a34d8-5df9-4ab3-be79-b8b34844eb3d",
    "created_at":"2019-11-05T22:23:31.126578-05:00",
    "application_id":"dc4152f7-456f-41ed-96b4-e52b8faa05fd",
    "user_id":"3fceea52-b71c-4b7f-bb88-712046523310",
    "provider":"vouched",
    "identifier":"oRM3YnSy",
    "type":"kyc",
    "status":"accepted",
    "name":"Joe Lubin",
    "description":null
  }
]

Create KYC Application

Create a KYC application using the specified third-party provider.

curl -i -XPUT \
        -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7fSwiZXhwIjpudWxsLCJpYXQiOjE1NTk4Nzg1NzQsImp0aSI6IjYzYTJkY2QzLWI5OTgtNDZjNC1hNzFkLTQ5MjU4YTBhYmEyMyIsInN1YiI6ImFwcGxpY2F0aW9uOmNiMjAzN2Y3LTc5ZmMtNDBmNC05NzIwLWFkYTYzNmRhNDE4MyJ9.NQLm__LbMWor-9GMG0LPcH4yQIbu9Uw70kJfRt1KP64' \
        https://bookie.provide.services/api/v1/kyc_applications/1bd7e730-67e5-4418-b624-c0c47b072f8b \
        -d '{
  "user_id":"00d4adc9-b0ca-4c94-9d90-3c61f696b8bd",
  "provider":"vouched",
  "params":{
    "type":"id-verification",
    "webhook_url":"https://url.to.my/webhook",
    "date_of_birth":"1988-10-01",
    "first_name":"John",
    "last_name":"Smith",
    "id_photo":"",
    "id_photo_back":"",
    "selfie":""
  }
}'
HTTP/2 201

Response JSON:

{
  "id":"205d1f45-4b45-4d85-a692-8db40d94ab89",
  "created_at":"2019-11-13T04:24:48.241681-05:00",
  "application_id":"dc4152f7-456f-41ed-96b4-e52b8faa05fd",
  "user_id":"00d4adc9-b0ca-4c94-9d90-3c61f696b8bd",
  "provider":"vouched",
  "identifier":null,
  "type":"kyc",
  "status":"pending",
  "name":"John Smith",
  "description":null,
  "params":{
    "date_of_birth":"1988-10-01",
    "first_name":"John",
    "last_name":"Smith",
    "id_photo":"",
    "id_photo_back":"",
    "selfie":"",
    "type":"id-verification",
    "webhook_url":"https://url.to.my/webhook"
  }
}

Request Parameters

Name	Type	Default	Description
provider	string	vouched	third-party KYC provider; delegate to which the API gateway will dispatch the KYC or KYB application
params	object	nil	KYC application parameters, normalized for generic use with any supported provider; a nested params object, if included within this parameter, is completely passed through to the third-party provider API
type	string	kyc	KYC application type (kyc or kyb)
user_id	uuid	--	id of the User which is the subject of the KYC application; this parameter is only relevant if calling the API on behalf of an Application

For provider-specific params reference, please see Third-Party API Support.

Update KYC Application

Update a previously submitted KYC application and asynchronously resubmit it to the third-party provider on behalf of the authorized User or Application.

curl -i -XPUT \
        -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7fSwiZXhwIjpudWxsLCJpYXQiOjE1NTk4Nzg1NzQsImp0aSI6IjYzYTJkY2QzLWI5OTgtNDZjNC1hNzFkLTQ5MjU4YTBhYmEyMyIsInN1YiI6ImFwcGxpY2F0aW9uOmNiMjAzN2Y3LTc5ZmMtNDBmNC05NzIwLWFkYTYzNmRhNDE4MyJ9.NQLm__LbMWor-9GMG0LPcH4yQIbu9Uw70kJfRt1KP64' \
        https://bookie.provide.services/api/v1/kyc_applications/1bd7e730-67e5-4418-b624-c0c47b072f8b \
        -d '{
  "status": "accepted"
}'
HTTP/2 202

Response JSON:

{
  "application_id":"dc4152f7-456f-41ed-96b4-e52b8faa05fd",
  "created_at":"2019-11-13T04:24:48.241681-05:00",
  "description":null,
  "id":"205d1f45-4b45-4d85-a692-8db40d94ab89",
  "identifier":"VS5eRURs",
  "name":"Truong Tri Tung",
  "provider":"vouched",
  "status":"accepted",
  "type":"kyc",
  "user_id":"9a253758-197a-4308-8d2d-61cfe9317644"
}

Request Parameters

Name	Type	Default	Description
status	string	vouched	the status of the KYC application; must be a valid state transition in the context of the application's current state

For provider-specific params reference, please see Third-Party API Support.

KYC Application Status & Accepting or Rejecting a KYC Application

The status parameter represents the current status of the KYC application; the following are valid status values:

Value	Description
accepted	the KYC application was accepted
failed	the KYC application submission to the third-party provider failed
pending	the KYC application is in the process of being submitted to the third-party provider
rejected	the KYC application was rejected, either by the third-party provider AI, or manually by way of remediation
remediate	the KYC application requires remediation due to its similarity with another KYC application or other risk factors
review	the KYC application has been submitted to the third-party provider and is currently being processed
submitted	the KYC application has been submitted to the third-party provider but no decision has been resolved

Retrieve KYC Application Details

Retrieve a previously submitted KYC application and enrich it with the latest third-party representation. This is useful to check the remediation status of an application.

curl -i \
     -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7fSwiZXhwIjpudWxsLCJpYXQiOjE1NTk4Nzg1NzQsImp0aSI6IjYzYTJkY2QzLWI5OTgtNDZjNC1hNzFkLTQ5MjU4YTBhYmEyMyIsInN1YiI6ImFwcGxpY2F0aW9uOmNiMjAzN2Y3LTc5ZmMtNDBmNC05NzIwLWFkYTYzNmRhNDE4MyJ9.NQLm__LbMWor-9GMG0LPcH4yQIbu9Uw70kJfRt1KP64' \
     https://bookie.provide.services/api/v1/kyc_applications/1bd7e730-67e5-4418-b624-c0c47b072f8b
HTTP/2 200

Response JSON (IdentityMind provider):

{
  "id":"1bd7e730-67e5-4418-b624-c0c47b072f8b",
  "created_at":"2019-06-07T02:30:00.115517-04:00",
  "application_id":null,
  "user_id":"00d4adc9-b0ca-4c94-9d90-3c61f696b8bd",
  "provider":"identitymind",
  "identifier":"95ed799287ee48ccadf4cf1f654e064c",
  "type":"kyc",
  "status":"accepted",
  "description":null,
  "params":{
    "man":"Joe Lubin",
    "tea":"[e-mail]"
  },
  "provider_representation":{
    "ednaScoreCard":{
      "er":{
        "profile":"DEFAULT",
        "reportedRule":{
          "description":"Rule fired from sandbox",
          "details":"[Fired] details",
          "name":"Sandbox Rule",
          "resultCode":"ACCEPT",
          "ruleId":1002,
          "testResults":[
            {
              "condition":{
                "left":"ed:1",
                "operator":"eq",
                "right":true
              },
              "details":"[Fired] details",
              "fired":true,
              "stage":"1",
              "test":"ed:1",
              "ts":1559891359000
            }
          ]
        }
      },
      "etr":[
        {
          "details":"true",
          "test":"ed:20"
        },
        {
          "details":"true",
          "test":"ed:31"
        },
        {
          "details":"true",
          "test":"ed:2"
        },
        {
          "details":"true",
          "test":"ed:1"
        },
        {
          "details":"true",
          "test":"ed:28"
        }
      ],
      "sc":[
        {
          "details":"true",
          "test":"ed:1"
        }
      ]
    },
    "mtid":"95ed799287ee48ccadf4cf1f654e064c",
    "rcd":"",
    "state":"A",
    "tid":"95ed799287ee48ccadf4cf1f654e064c"
  }
}

Response JSON (Vouched provider):

{
  "id":"e494ee10-bbf5-45bb-81aa-7e3561d8c729",
  "created_at":"2019-09-15T02:42:00.743047-04:00",
  "application_id":"dc4152f7-456f-41ed-96b4-e52b8faa05fd",
  "user_id":"9e15791a-dbf1-4e5e-8c6b-a7253e198b4c",
  "provider":"vouched",
  "identifier":"hDj_HOv",
  "type":"kyc",
  "status":"submitted",
  "description":null,
  "params":{
    "params":{
      "date_of_birth":"06/22/1990",
      "first_name":"Janice",
      "last_name":"Way",
      "id_photo":"",
      "id_photo_back":"",
      "selfie":"",
      "type":"id-verification",
      "webhook_url":null
    },
    "type":"id-verification"
  },
  "provider_representation":{
    "errors":[
      {
        "message":"Invalid or unsupported id",
        "suggestion":null,
        "type":"InvalidIdPhotoError"
      },
      {
        "message":"Invalid or unsupported selfie",
        "suggestion":null,
        "type":"InvalidUserPhotoError"
      },
      {
        "message":"Id and selfie faces do not match",
        "suggestion":null,
        "type":"FaceMatchError"
      },
      {
        "message":"Name is below the confidence threshold",
        "suggestion":null,
        "type":"NameMatchError"
      },
      {
        "message":"Birth date is below the confidence threshold",
        "suggestion":null,
        "type":"BirthDateMatchError"
      }
    ],
    "id":"hDj_HOv",
    "request":{
      "callbackURL":"https://google.com/gdpr",
      "parameters":{
        "carInsurancePhoto":null,
        "dob":"06/22/1990",
        "dotPhoto":null,
        "firstName":"Janice",
        "idPhoto":"",
        "idPhotoBack":null,
        "lastName":"Way",
        "twicPhoto":null,
        "userPhoto":""
      },
      "type":"id-verification"
    },
    "result":{
      "confidences":{
        "backId":null,
        "faceMatch":0,
        "id":0.4327,
        "idMatch":0,
        "selfie":0.0434
      },
      "country":"US",
      "dob":null,
      "errors":null,
      "firstName":null,
      "id":null,
      "lastName":null,
      "state":"WI",
      "success":false,
      "type":"drivers-license"
    },
    "status":"completed",
    "submitted":"2019-09-15T06:42:02+00:00"
  }
}